Finished documentation and example

doc/txt/compute_sna_atom.txt

@@ -9,12 +9,14 @@
 compute sna/atom command :h3
 compute snad/atom command :h3
 compute snav/atom command :h3
+compute snap command :h3
 
 [Syntax:]
 
 compute ID group-ID sna/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ...
 compute ID group-ID snad/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ...
-compute ID group-ID snav/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... :pre
+compute ID group-ID snav/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... 
+compute ID group-ID snap rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... :pre
 
 ID, group-ID are documented in "compute"_compute.html command :ulb,l
 sna/atom = style name of this compute command :l
@@ -41,12 +43,17 @@ keyword = {rmin0} or {switchflag} or {bzeroflag} or {quadraticflag} :l
 
 compute b all sna/atom 1.4 0.99363 6 2.0 2.4 0.75 1.0 rmin0 0.0
 compute db all sna/atom 1.4 0.95 6 2.0 1.0
-compute vb all sna/atom 1.4 0.95 6 2.0 1.0 :pre
+compute vb all sna/atom 1.4 0.95 6 2.0 1.0
+compute snap all snap 1.4 0.95 6 2.0 1.0 :pre
 
 [Description:]
 
-Define a computation that calculates a set of bispectrum components
+Define a computation that calculates a set of quantities related to the
-for each atom in a group.
+bispectrum components of the atoms in a group. These computes are
+used primarily for calculating the dependence of energy, force, and
+stress components on the linear coefficients in the 
+"snap pair_style"_pair_snap.html, which is useful when training a
+SNAP potential to match target data.
 
 Bispectrum components of an atom are order parameters characterizing
 the radial and angular distribution of neighbor atoms. The detailed
@@ -130,6 +137,26 @@ Again, the sum is over all atoms {i'} of atom type {I}.  For each atom
 virial components, each atom type, and each bispectrum component.  See
 section below on output for a detailed explanation.
 
+Compute {snap} calculates a global array contains information related
+to all three of the preceding per-atom computes {sna/atom}, {snad/atom},
+and {snav/atom}. The first row of the array contains the summation of 
+{sna/atom} over all atoms, but broken out by type. The last six rows
+of the array contain the summation of {snav/atom} over all atoms, broken
+out by type. In between these are 3*N rows containing the same values
+computed by {snad/atom} (these are already summed over all atoms and
+broken out by type). The element in the last column of each row contains
+the corresponding contribution to potential energy, force, or stress. 
+These quantities correspond to the user-specified refence potential
+that must be subtracted from the target data when fitting SNAP.
+The potential energy calculation uses the built in compute {thermo_pe}.
+The stess calculation requires that a compute called {snap_press}
+be defined using the following command:
+
+compute snap_press all pressure NULL virial :pre
+
+See section below on output for a detailed explanation of the data
+layout in the global array.
+
 The value of all bispectrum components will be zero for atoms not in
 the group. Neighbor atoms not in the group do not contribute to the
 bispectrum of atoms in the group.
@@ -214,10 +241,27 @@ block contains six sub-blocks corresponding to the {xx}, {yy}, {zz},
 notation.  Each of these sub-blocks contains one column for each
 bispectrum component, the same as for compute {sna/atom}
 
+Compute {snap} evaluates a global array. 
+The columns are arranged into
+{ntypes} blocks, listed in order of atom type {I}. Each block
+contains one column for each bispectrum component, the same as for compute
+{sna/atom}. A final column contains the corresponding energy, force component
+on an atom, and virial stress component. The rows of the array appear 
+in the following order:
+
+   1 row: {sna/atom} quantities summed for all atoms of type {I}
+   3*N rows: {snad/atom} quantities, with derivatives w.r.t x, y, and z 
+coordinate of atom {i} appearing in consecutive rows. The atoms
+are sorted based on atom ID.
+   6 rows: {snav/atom} quantities summed for all atoms of type {I} :ul
+
 For example, if {K} =30 and ntypes=1, the number of columns in the per-atom
 arrays generated by {sna/atom}, {snad/atom}, and {snav/atom}
 are 30, 90, and 180, respectively. With {quadratic} value=1,
 the numbers of columns are 930, 2790, and 5580, respectively.
+The number of columns in the global array generated by {snap}
+are 31, and 931, respectively, while the number of rows is
+1+3*{N} +6, where {N} is the total number of atoms.
 
 If the {quadratic} keyword value is set to 1, then additional
 columns are generated, corresponding to

examples/snap/in.snap.compute

@@ -1,6 +1,6 @@
 # Demonstrate bispectrum computes
 
-# Initialize simulation
+# initialize simulation
 
 variable 	nsteps index 0
 variable 	nrep equal 1
@@ -35,14 +35,15 @@ variable 	radelem1 equal 2.3
 variable 	radelem2 equal 2.0
 variable	wj1 equal 1.0
 variable	wj2 equal 0.96
+variable 	snap_options string &
+"${rcutfac} ${rfac0} ${twojmax} ${radelem1} ${radelem2} ${wj1} ${wj2} rmin0 ${rmin0} quadraticflag 0 bzeroflag 0 switchflag 0"
 
-
+# set up dummy potential to satisfy cutoff
-# Setup dummy potential to satisfy cutoff
 
 pair_style 	zero ${rcutfac}
 pair_coeff 	* *
 
-# Setup reference potential
+# set up reference potential
 
 variable 	zblcutinner equal 4
 variable 	zblcutouter equal 4.8
@@ -50,11 +51,11 @@ variable 	zblz equal 73
 pair_style 	zbl ${zblcutinner} ${zblcutouter}
 pair_coeff 	* * ${zblz} ${zblz}
 
-# set up old-style per-atom computes
+# set up per-atom computes
 
-compute 	b all sna/atom ${rcutfac} ${rfac0} ${twojmax} ${radelem1} ${radelem2} ${wj1} ${wj2} rmin0 ${rmin0} quadraticflag 0 bzeroflag 0 switchflag 0
+compute 	b all sna/atom ${snap_options}
-compute 	vb all snav/atom ${rcutfac} ${rfac0} ${twojmax} ${radelem1} ${radelem2} ${wj1} ${wj2} rmin0 ${rmin0} quadraticflag 0 bzeroflag 0 switchflag 0
+compute 	vb all snav/atom ${snap_options}
-compute 	db all snad/atom ${rcutfac} ${rfac0} ${twojmax} ${radelem1} ${radelem2} ${wj1} ${wj2} rmin0 ${rmin0} quadraticflag 0 bzeroflag 0 switchflag 0
+compute 	db all snad/atom ${snap_options}
 
 # perform sums over atoms
 
@@ -67,9 +68,9 @@ compute         bsum2 snapgroup2 reduce sum c_b[*]
 compute		vbsum all reduce sum c_vb[*]
 # fix 		vbsum all ave/time 1 1 1 c_vbsum file vbsum.dat mode vector
 
-# set up new-style global compute
+# set up compute snap generating global array
 
-compute 	snap all snap ${rcutfac} ${rfac0} ${twojmax} ${radelem1} ${radelem2} ${wj1} ${wj2} rmin0 ${rmin0} quadraticflag 0 bzeroflag 0 switchflag 0
+compute 	snap all snap ${snap_options}
 fix 		snap all ave/time 1 1 1 c_snap[*] file compute.snap.dat mode vector
 
 thermo 		100