kim-api  2.1.3+v2.1.3.GNU An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
Go to the documentation of this file.
1 #
3 #
4 # The contents of this file are subject to the terms of the Common Development
6 #
7 # You can obtain a copy of the license at
9 # specific language governing permissions and limitations under the License.
10 #
11 # When distributing Covered Code, include this CDDL HEADER in each file and
12 # include the License file in a prominent location with the name LICENSE.CDDL.
13 # If applicable, add the following below this CDDL HEADER, with the fields
14 # enclosed by brackets "[]" replaced with your own identifying information:
15 #
17 #
19 #
20
21 #
22 # Copyright (c) 2013--2019, Regents of the University of Minnesota.
24 #
25 # Contributors:
27 # Ryan S. Elliott
28 #
29
30
31 This directory (utility_forces_numer_deriv) contains a Verification Check that
32 compares the forces computed by a KIM-compliant Model with those obtained using
33 numerical differentiation of the Model energies.
34
35 Calling format:
36
37  printf "model_name" | ./utility_forces_numer_deriv
38
39 Notes:
40
41 1. It checks a single configuration: a perturbed fcc cluster made of a random
42  arrangement of the supported species with spacing scaled by a factor based
43  on the Model's cutoff value.
44
45 2. The code computes the DIM*N components of the force vector in two ways:
46  directly using the Model's force calculation (force_model') and by
47  numerical differentiation using Ridders' method (force_numer'). The
48  difference between these values in absolute value is also printed (Force
49  diff') as well as the error predicted by Ridders' method (pred error').
50  Ideally, one would expect the force difference to be less than the predicted
51  error. If that is the case the term `ok' is printed at the end of the
52  line. (Most potentials fail this check for most degrees of freedom, so this
53  is not a good criterion.)
54
55  In addition, the following normalized measure is computed:
56
57  \alpha = 1/(DIM*N) sqrt( \sum_i w_i (f^{model}_i - f^{numer}_i)^2 / \sum_i w_i ),
58
59  where w_i is the weight associated with term i:
60
61  w_i = 1/\hat{\epsilon}_i,
62
63  and \hat{\epsilon}_i is the normalized error in the numerical calculation:
64
65  \hat{\epsilon}_i = max(\epsilon^{numer}_i, \epsilon^{prec}) /
66  max(\force^{numer}_i, \epsilon^{prec})
67
68  The max functions impose a lower limit on computed values equal to the
69  numerical precision of the computer (\epsilon^{prec}).
70
71  \alpha has units of force and can be understood as the average error per
72  degree of freedom. The smaller the value of \alpha the more accurate the
73  force calculation of the Model.
74
75  In the expression for \alpha each term is weighted by the relative accuracy
76  of the numerical estimate for the derivative. Thus if f^{numer}_i is a poor
77  estimate for the derivative (i.e. \epsilon^{numer}_i is large relative to
78  f^{numer}_i) then term i contributes less to \alpha since it is less
79  trustworthy.
80
81  In addition to \alpha, the maximum term contributing to \alpha is
82  identified. For this degree of freedom, the error and normalized error are
83  printed:
84
85  forcediff_i = |f^{model}_i - f^{numer}_i}|
86
87  forcediff_i/|f^{model}_i|
88
89  This is *not* the largest error (i.e. the largest value of forcediff_i) due
90  to the weighting term w_i. Simply looking at the maximum value of
91  forcediff_i could be misleading since the error in the numerical term,
92  \epsilon^{numer}_i, may be large for the component. Instead the maximum of
93  w_i*forcediff_i is a compromise that in some sense seeks the largest error
94  for components where the numerical derivative are also as accurate possible.