doc/src/compute_sna_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 compute sna/atom command :h3
  10 compute snad/atom command :h3
  11 compute snav/atom command :h3
  12
  13 [Syntax:]
  14
  15 compute ID group-ID sna/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ...
  16 compute ID group-ID snad/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ...
  17 compute ID group-ID snav/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... :pre
  18
  19 ID, group-ID are documented in "compute"_compute.html command :ulb,l
  20 sna/atom = style name of this compute command :l
  21 rcutfac = scale factor applied to all cutoff radii (positive real) :l
  22 rfac0 = parameter in distance to angle conversion (0 < rcutfac < 1) :l
  23 twojmax = band limit for bispectrum components (non-negative integer) :l
  24 R_1, R_2,... = list of cutoff radii, one for each type (distance units) :l
  25 w_1, w_2,... = list of neighbor weights, one for each type  :l
  26 zero or more keyword/value pairs may be appended :l
  27 keyword = {diagonal} or {rmin0} or {switchflag} :l
  28   {diagonal} value = {0} or {1} or {2} or {3}
  29      {0} = all j1, j2, j <= twojmax, j2 <= j1
  30      {1} = subset satisfying j1 == j2
  31      {2} = subset satisfying j1 == j2 == j3
  32      {3} = subset satisfying j2 <= j1 <= j
  33   {rmin0} value = parameter in distance to angle conversion (distance units)
  34   {switchflag} value = {0} or {1}
  35      {0} = do not use switching function
  36      {1} = use switching function :pre
  37 :ule
  38
  39 [Examples:]
  40
  41 compute b all sna/atom 1.4 0.99363 6 2.0 2.4 0.75 1.0 diagonal 3 rmin0 0.0
  42 compute db all sna/atom 1.4 0.95 6 2.0 1.0
  43 compute vb all sna/atom 1.4 0.95 6 2.0 1.0 :pre
  44
  45 [Description:]
  46
  47 Define a computation that calculates a set of bispectrum components
  48 for each atom in a group.
  49
  50 Bispectrum components of an atom are order parameters characterizing
  51 the radial and angular distribution of neighbor atoms. The detailed
  52 mathematical definition is given in the paper by Thompson et
  53 al. "(Thompson)"_#Thompson2014
  54
  55 The position of a neighbor atom {i'} relative to a central atom {i} is
  56 a point within the 3D ball of radius {R_ii' = rcutfac*(R_i + R_i')}
  57
  58 Bartok et al. "(Bartok)"_#Bartok2010, proposed mapping this 3D ball
  59 onto the 3-sphere, the surface of the unit ball in a four-dimensional
  60 space.  The radial distance {r} within {R_ii'} is mapped on to a third
  61 polar angle {theta0} defined by,
  62
  63 :c,image(Eqs/compute_sna_atom1.jpg)
  64
  65 In this way, all possible neighbor positions are mapped on to a subset
  66 of the 3-sphere.  Points south of the latitude {theta0max=rfac0*Pi}
  67 are excluded.
  68
  69 The natural basis for functions on the 3-sphere is formed by the 4D
  70 hyperspherical harmonics {U^j_m,m'(theta, phi, theta0).}  These
  71 functions are better known as {D^j_m,m',} the elements of the Wigner
  72 {D}-matrices "(Meremianin"_#Meremianin2006,
  73 "Varshalovich)"_#Varshalovich1987.
  74
  75 The density of neighbors on the 3-sphere can be written as a sum of
  76 Dirac-delta functions, one for each neighbor, weighted by species and
  77 radial distance. Expanding this density function as a generalized
  78 Fourier series in the basis functions, we can write each Fourier
  79 coefficient as
  80
  81 :c,image(Eqs/compute_sna_atom2.jpg)
  82
  83 The {w_i'} neighbor weights are dimensionless numbers that are chosen
  84 to distinguish atoms of different types, while the central atom is
  85 arbitrarily assigned a unit weight.  The function {fc(r)} ensures that
  86 the contribution of each neighbor atom goes smoothly to zero at
  87 {R_ii'}:
  88
  89 :c,image(Eqs/compute_sna_atom4.jpg)
  90
  91 The expansion coefficients {u^j_m,m'} are complex-valued and they are
  92 not directly useful as descriptors, because they are not invariant
  93 under rotation of the polar coordinate frame. However, the following
  94 scalar triple products of expansion coefficients can be shown to be
  95 real-valued and invariant under rotation "(Bartok)"_#Bartok2010.
  96
  97 :c,image(Eqs/compute_sna_atom3.jpg)
  98
  99 The constants {H^jmm'_j1m1m1'_j2m2m2'} are coupling coefficients,
 100 analogous to Clebsch-Gordan coefficients for rotations on the
 101 2-sphere. These invariants are the components of the bispectrum and
 102 these are the quantities calculated by the compute {sna/atom}. They
 103 characterize the strength of density correlations at three points on
 104 the 3-sphere. The j2=0 subset form the power spectrum, which
 105 characterizes the correlations of two points. The lowest-order
 106 components describe the coarsest features of the density function,
 107 while higher-order components reflect finer detail.  Note that the
 108 central atom is included in the expansion, so three point-correlations
 109 can be either due to three neighbors, or two neighbors and the central
 110 atom.
 111
 112 Compute {snad/atom} calculates the derivative of the bispectrum components
 113 summed separately for each atom type:
 114
 115 :c,image(Eqs/compute_sna_atom5.jpg)
 116
 117 The sum is over all atoms {i'} of atom type {I}.  For each atom {i},
 118 this compute evaluates the above expression for each direction, each
 119 atom type, and each bispectrum component.  See section below on output
 120 for a detailed explanation.
 121
 122 Compute {snav/atom} calculates the virial contribution due to the
 123 derivatives:
 124
 125 :c,image(Eqs/compute_sna_atom6.jpg)
 126
 127 Again, the sum is over all atoms {i'} of atom type {I}.  For each atom
 128 {i}, this compute evaluates the above expression for each of the six
 129 virial components, each atom type, and each bispectrum component.  See
 130 section below on output for a detailed explanation.
 131
 132 The value of all bispectrum components will be zero for atoms not in
 133 the group. Neighbor atoms not in the group do not contribute to the
 134 bispectrum of atoms in the group.
 135
 136 The neighbor list needed to compute this quantity is constructed each
 137 time the calculation is performed (i.e. each time a snapshot of atoms
 138 is dumped).  Thus it can be inefficient to compute/dump this quantity
 139 too frequently.
 140
 141 The argument {rcutfac} is a scale factor that controls the ratio of
 142 atomic radius to radial cutoff distance.
 143
 144 The argument {rfac0} and the optional keyword {rmin0} define the
 145 linear mapping from radial distance to polar angle {theta0} on the
 146 3-sphere.
 147
 148 The argument {twojmax} and the keyword {diagonal} define which
 149 bispectrum components are generated. See section below on output for a
 150 detailed explanation of the number of bispectrum components and the
 151 ordered in which they are listed
 152
 153 The keyword {switchflag} can be used to turn off the switching
 154 function.
 155
 156 NOTE: If you have a bonded system, then the settings of
 157 "special_bonds"_special_bonds.html command can remove pairwise
 158 interactions between atoms in the same bond, angle, or dihedral.  This
 159 is the default setting for the "special_bonds"_special_bonds.html
 160 command, and means those pairwise interactions do not appear in the
 161 neighbor list.  Because this fix uses the neighbor list, it also means
 162 those pairs will not be included in the calculation.  One way to get
 163 around this, is to write a dump file, and use the "rerun"_rerun.html
 164 command to compute the bispectrum components for snapshots in the dump
 165 file.  The rerun script can use a "special_bonds"_special_bonds.html
 166 command that includes all pairs in the neighbor list.
 167
 168 ;line
 169
 170 [Output info:]
 171
 172 Compute {sna/atom} calculates a per-atom array, each column
 173 corresponding to a particular bispectrum component.  The total number
 174 of columns and the identities of the bispectrum component contained in
 175 each column depend on the values of {twojmax} and {diagonal}, as
 176 described by the following piece of python code:
 177
 178 for j1 in range(0,twojmax+1):
 179     if(diagonal==2):
 180         print j1/2.,j1/2.,j1/2.
 181     elif(diagonal==1):
 182         for j in range(0,min(twojmax,2*j1)+1,2):
 183             print j1/2.,j1/2.,j/2.
 184     elif(diagonal==0):
 185         for j2 in range(0,j1+1):
 186             for j in range(j1-j2,min(twojmax,j1+j2)+1,2):
 187                 print j1/2.,j2/2.,j/2.
 188     elif(diagonal==3):
 189         for j2 in range(0,j1+1):
 190             for j in range(j1-j2,min(twojmax,j1+j2)+1,2):
 191                 if (j>=j1): print j1/2.,j2/2.,j/2. :pre
 192
 193 Compute {snad/atom} evaluates a per-atom array. The columns are
 194 arranged into {ntypes} blocks, listed in order of atom type {I}.  Each
 195 block contains three sub-blocks corresponding to the {x}, {y}, and {z}
 196 components of the atom position.  Each of these sub-blocks contains
 197 one column for each bispectrum component, the same as for compute
 198 {sna/atom}
 199
 200 Compute {snav/atom} evaluates a per-atom array. The columns are
 201 arranged into {ntypes} blocks, listed in order of atom type {I}.  Each
 202 block contains six sub-blocks corresponding to the {xx}, {yy}, {zz},
 203 {yz}, {xz}, and {xy} components of the virial tensor in Voigt
 204 notation.  Each of these sub-blocks contains one column for each
 205 bispectrum component, the same as for compute {sna/atom}
 206
 207 These values can be accessed by any command that uses per-atom values
 208 from a compute as input.  See "Section
 209 6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output
 210 options.
 211
 212 [Restrictions:]
 213
 214 These computes are part of the SNAP package.  They are only enabled if
 215 LAMMPS was built with that package.  See the "Making
 216 LAMMPS"_Section_start.html#start_3 section for more info.
 217
 218 [Related commands:]
 219
 220 "pair_style snap"_pair_snap.html
 221
 222 [Default:]
 223
 224 The optional keyword defaults are {diagonal} = 0, {rmin0} = 0,
 225 {switchflag} = 1.
 226
 227 :line
 228
 229 :link(Thompson2014)
 230 [(Thompson)] Thompson, Swiler, Trott, Foiles, Tucker, under review, preprint
 231 available at "arXiv:1409.3880"_http://arxiv.org/abs/1409.3880
 232
 233 :link(Bartok2010)
 234 [(Bartok)] Bartok, Payne, Risi, Csanyi, Phys Rev Lett, 104, 136403 (2010).
 235
 236 :link(Meremianin2006)
 237 [(Meremianin)] Meremianin, J. Phys. A,  39, 3099 (2006).
 238
 239 :link(Varshalovich1987)
 240 [(Varshalovich)] Varshalovich, Moskalev, Khersonskii, Quantum Theory
 241 of Angular Momentum, World Scientific, Singapore (1987).