kim-api  2.3.0+v2.3.0.GNU.GNU.
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
README
Go to the documentation of this file.
1 #
2 # KIM-API: An API for interatomic models
3 # Copyright (c) 2013--2022, Regents of the University of Minnesota.
4 # All rights reserved.
5 #
6 # Contributors:
7 # Ryan S. Elliott
8 # Ellad B. Tadmor
9 #
10 # SPDX-License-Identifier: LGPL-2.1-or-later
11 #
12 # This library is free software; you can redistribute it and/or
13 # modify it under the terms of the GNU Lesser General Public
14 # License as published by the Free Software Foundation; either
15 # version 2.1 of the License, or (at your option) any later version.
16 #
17 # This library is distributed in the hope that it will be useful,
18 # but WITHOUT ANY WARRANTY; without even the implied warranty of
19 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 # Lesser General Public License for more details.
21 #
22 # You should have received a copy of the GNU Lesser General Public License
23 # along with this library; if not, write to the Free Software Foundation,
24 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
25 #
26 
27 
28 This directory (utility_forces_numer_deriv) contains a Verification Check that
29 compares the forces computed by a KIM-compliant Model with those obtained using
30 numerical differentiation of the Model energies.
31 
32 Calling format:
33 
34  printf "model_name" | ./utility_forces_numer_deriv
35 
36 Notes:
37 
38 1. It checks a single configuration: a perturbed fcc cluster made of a random
39  arrangement of the supported species with spacing scaled by a factor based
40  on the Model's cutoff value.
41 
42 2. The code computes the DIM*N components of the force vector in two ways:
43  directly using the Model's force calculation (`force_model') and by
44  numerical differentiation using Ridders' method (`force_numer'). The
45  difference between these values in absolute value is also printed (`Force
46  diff') as well as the error predicted by Ridders' method (`pred error').
47  Ideally, one would expect the force difference to be less than the predicted
48  error. If that is the case the term `ok' is printed at the end of the
49  line. (Most potentials fail this check for most degrees of freedom, so this
50  is not a good criterion.)
51 
52  In addition, the following normalized measure is computed:
53 
54  \alpha = 1/(DIM*N) sqrt( \sum_i w_i (f^{model}_i - f^{numer}_i)^2 / \sum_i w_i ),
55 
56  where w_i is the weight associated with term i:
57 
58  w_i = 1/\hat{\epsilon}_i,
59 
60  and \hat{\epsilon}_i is the normalized error in the numerical calculation:
61 
62  \hat{\epsilon}_i = max(\epsilon^{numer}_i, \epsilon^{prec}) /
63  max(\force^{numer}_i, \epsilon^{prec})
64 
65  The max functions impose a lower limit on computed values equal to the
66  numerical precision of the computer (\epsilon^{prec}).
67 
68  \alpha has units of force and can be understood as the average error per
69  degree of freedom. The smaller the value of \alpha the more accurate the
70  force calculation of the Model.
71 
72  In the expression for \alpha each term is weighted by the relative accuracy
73  of the numerical estimate for the derivative. Thus if f^{numer}_i is a poor
74  estimate for the derivative (i.e. \epsilon^{numer}_i is large relative to
75  f^{numer}_i) then term i contributes less to \alpha since it is less
76  trustworthy.
77 
78  In addition to \alpha, the maximum term contributing to \alpha is
79  identified. For this degree of freedom, the error and normalized error are
80  printed:
81 
82  forcediff_i = |f^{model}_i - f^{numer}_i}|
83 
84  forcediff_i/|f^{model}_i|
85 
86  This is *not* the largest error (i.e. the largest value of forcediff_i) due
87  to the weighting term w_i. Simply looking at the maximum value of
88  forcediff_i could be misleading since the error in the numerical term,
89  \epsilon^{numer}_i, may be large for the component. Instead the maximum of
90  w_i*forcediff_i is a compromise that in some sense seeks the largest error
91  for components where the numerical derivative are also as accurate possible.