doc/src/compute_reduce.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 compute reduce command :h3
  10 compute reduce/region command :h3
  11
  12 [Syntax:]
  13
  14 compute ID group-ID style arg mode input1 input2 ... keyword args ... :pre
  15
  16 ID, group-ID are documented in "compute"_compute.html command :ulb,l
  17 style = {reduce} or {reduce/region} :l
  18   {reduce} arg = none
  19   {reduce/region} arg = region-ID
  20     region-ID = ID of region to use for choosing atoms :pre
  21 mode = {sum} or {min} or {max} or {ave} or {sumsq} or {avesq} :l
  22 one or more inputs can be listed :l
  23 input = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :l
  24   x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (position, velocity, force component)
  25   c_ID = per-atom or local vector calculated by a compute with ID
  26   c_ID\[I\] = Ith column of per-atom or local array calculated by a compute with ID, I can include wildcard (see below)
  27   f_ID = per-atom or local vector calculated by a fix with ID
  28   f_ID\[I\] = Ith column of per-atom or local array calculated by a fix with ID, I can include wildcard (see below)
  29   v_name = per-atom vector calculated by an atom-style variable with name :pre
  30
  31 zero or more keyword/args pairs may be appended :l
  32 keyword = {replace} :l
  33   {replace} args = vec1 vec2
  34     vec1 = reduced value from this input vector will be replaced
  35     vec2 = replace it with vec1\[N\] where N is index of max/min value from vec2 :pre
  36 :ule
  37
  38 [Examples:]
  39
  40 compute 1 all reduce sum c_force
  41 compute 1 all reduce/region subbox sum c_force
  42 compute 2 all reduce min c_press\[2\] f_ave v_myKE
  43 compute 2 all reduce min c_press\[*\] f_ave v_myKE
  44 compute 3 fluid reduce max c_index\[1\] c_index\[2\] c_dist replace 1 3 replace 2 3 :pre
  45
  46 [Description:]
  47
  48 Define a calculation that "reduces" one or more vector inputs into
  49 scalar values, one per listed input.  The inputs can be per-atom or
  50 local quantities; they cannot be global quantities.  Atom attributes
  51 are per-atom quantities, "computes"_compute.html and "fixes"_fix.html
  52 may generate any of the three kinds of quantities, and "atom-style
  53 variables"_variable.html generate per-atom quantities.  See the
  54 "variable"_variable.html command and its special functions which can
  55 perform the same operations as the compute reduce command on global
  56 vectors.
  57
  58 The reduction operation is specified by the {mode} setting.  The {sum}
  59 option adds the values in the vector into a global total.  The {min}
  60 or {max} options find the minimum or maximum value across all vector
  61 values.  The {ave} setting adds the vector values into a global total,
  62 then divides by the number of values in the vector.  The {sumsq}
  63 option sums the square of the values in the vector into a global
  64 total.  The {avesq} setting does the same as {sumsq}, then divdes the
  65 sum of squares by the number of values.  The last two options can be
  66 useful for calculating the variance of some quantity, e.g. variance =
  67 sumsq - ave^2.
  68
  69 Each listed input is operated on independently.  For per-atom inputs,
  70 the group specified with this command means only atoms within the
  71 group contribute to the result.  For per-atom inputs, if the compute
  72 reduce/region command is used, the atoms must also currently be within
  73 the region.  Note that an input that produces per-atom quantities may
  74 define its own group which affects the quantities it returns.  For
  75 example, if a compute is used as an input which generates a per-atom
  76 vector, it will generate values of 0.0 for atoms that are not in the
  77 group specified for that compute.
  78
  79 Each listed input can be an atom attribute (position, velocity, force
  80 component) or can be the result of a "compute"_compute.html or
  81 "fix"_fix.html or the evaluation of an atom-style
  82 "variable"_variable.html.
  83
  84 Note that for values from a compute or fix, the bracketed index I can
  85 be specified using a wildcard asterisk with the index to effectively
  86 specify multiple values.  This takes the form "*" or "*n" or "n*" or
  87 "m*n".  If N = the size of the vector (for {mode} = scalar) or the
  88 number of columns in the array (for {mode} = vector), then an asterisk
  89 with no numeric values means all indices from 1 to N.  A leading
  90 asterisk means all indices from 1 to n (inclusive).  A trailing
  91 asterisk means all indices from n to N (inclusive).  A middle asterisk
  92 means all indices from m to n (inclusive).
  93
  94 Using a wildcard is the same as if the individual columns of the array
  95 had been listed one by one.  E.g. these 2 compute reduce commands are
  96 equivalent, since the "compute stress/atom"_compute_stress_atom.html
  97 command creates a per-atom array with 6 columns:
  98
  99 compute myPress all stress/atom NULL
 100 compute 2 all reduce min myPress\[*\]
 101 compute 2 all reduce min myPress\[1\] myPress\[2\] myPress\[3\] &
 102                          myPress\[4\] myPress\[5\] myPress\[6\] :pre
 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 If a value begins with "c_", a compute ID must follow which has been
 113 previously defined in the input script.  Computes can generate
 114 per-atom or local quantities.  See the individual
 115 "compute"_compute.html doc page for details.  If no bracketed integer
 116 is appended, the vector calculated by the compute is used.  If a
 117 bracketed integer is appended, the Ith column of the array calculated
 118 by the compute is used.  Users can also write code for their own
 119 compute styles and "add them to LAMMPS"_Section_modify.html.  See the
 120 discussion above for how I can be specified with a wildcard asterisk
 121 to effectively specify multiple values.
 122
 123 If a value begins with "f_", a fix ID must follow which has been
 124 previously defined in the input script.  Fixes can generate per-atom
 125 or local quantities.  See the individual "fix"_fix.html doc page for
 126 details.  Note that some fixes only produce their values on certain
 127 timesteps, which must be compatible with when compute reduce
 128 references the values, else an error results.  If no bracketed integer
 129 is appended, the vector calculated by the fix is used.  If a bracketed
 130 integer is appended, the Ith column of the array calculated by the fix
 131 is used.  Users can also write code for their own fix style and "add
 132 them to LAMMPS"_Section_modify.html.  See the discussion above for how
 133 I can be specified with a wildcard asterisk to effectively specify
 134 multiple values.
 135
 136 If a value begins with "v_", a variable name must follow which has
 137 been previously defined in the input script.  It must be an
 138 "atom-style variable"_variable.html.  Atom-style variables can
 139 reference thermodynamic keywords and various per-atom attributes, or
 140 invoke other computes, fixes, or variables when they are evaluated, so
 141 this is a very general means of generating per-atom quantities to
 142 reduce.
 143
 144 :line
 145
 146 If the {replace} keyword is used, two indices {vec1} and {vec2} are
 147 specified, where each index ranges from 1 to the # of input values.
 148 The replace keyword can only be used if the {mode} is {min} or {max}.
 149 It works as follows.  A min/max is computed as usual on the {vec2}
 150 input vector.  The index N of that value within {vec2} is also stored.
 151 Then, instead of performing a min/max on the {vec1} input vector, the
 152 stored index is used to select the Nth element of the {vec1} vector.
 153
 154 Thus, for example, if you wish to use this compute to find the bond
 155 with maximum stretch, you can do it as follows:
 156
 157 compute 1 all property/local batom1 batom2
 158 compute 2 all bond/local dist
 159 compute 3 all reduce max c_1\[1\] c_1\[2\] c_2 replace 1 3 replace 2 3
 160 thermo_style custom step temp c_3\[1\] c_3\[2\] c_3\[3\] :pre
 161
 162 The first two input values in the compute reduce command are vectors
 163 with the IDs of the 2 atoms in each bond, using the "compute
 164 property/local"_compute_property_local.html command.  The last input
 165 value is bond distance, using the "compute
 166 bond/local"_compute_bond_local.html command.  Instead of taking the
 167 max of the two atom ID vectors, which does not yield useful
 168 information in this context, the {replace} keywords will extract the
 169 atom IDs for the two atoms in the bond of maximum stretch.  These atom
 170 IDs and the bond stretch will be printed with thermodynamic output.
 171
 172 :line
 173
 174 If a single input is specified this compute produces a global scalar
 175 value.  If multiple inputs are specified, this compute produces a
 176 global vector of values, the length of which is equal to the number of
 177 inputs specified.
 178
 179 As discussed below, for the {sum} and {sumsq} modes, the value(s)
 180 produced by this compute are all "extensive", meaning their value
 181 scales linearly with the number of atoms involved.  If normalized
 182 values are desired, this compute can be accessed by the "thermo_style
 183 custom"_thermo_style.html command with "thermo_modify norm
 184 yes"_thermo_modify.html set as an option.  Or it can be accessed by a
 185 "variable"_variable.html that divides by the appropriate atom count.
 186
 187 :line
 188
 189 [Output info:]
 190
 191 This compute calculates a global scalar if a single input value is
 192 specified or a global vector of length N where N is the number of
 193 inputs, and which can be accessed by indices 1 to N.  These values can
 194 be used by any command that uses global scalar or vector values from a
 195 compute as input.  See "Section 6.15"_Section_howto.html#howto_15
 196 for an overview of LAMMPS output options.
 197
 198 All the scalar or vector values calculated by this compute are
 199 "intensive", except when the {sum} or {sumsq} modes are used on
 200 per-atom or local vectors, in which case the calculated values are
 201 "extensive".
 202
 203 The scalar or vector values will be in whatever "units"_units.html the
 204 quantities being reduced are in.
 205
 206 [Restrictions:] none
 207
 208 [Related commands:]
 209
 210 "compute"_compute.html, "fix"_fix.html, "variable"_variable.html
 211
 212 [Default:] none