#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the Common Development
# and Distribution License Version 1.0 (the "License").
#
# You can obtain a copy of the license at
# http://www.opensource.org/licenses/CDDL-1.0.  See the License for the
# specific language governing permissions and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each file and
# include the License file in a prominent location with the name LICENSE.CDDL.
# If applicable, add the following below this CDDL HEADER, with the fields
# enclosed by brackets "[]" replaced with your own identifying information:
#
# Portions Copyright (c) [yyyy] [name of copyright owner]. All rights reserved.
#
# CDDL HEADER END
#

#
# Copyright (c) 2013--2014, Regents of the University of Minnesota.
# All rights reserved.
#
# Contributors:
#    Ellad B. Tadmor
#    Ryan S. Elliott
#

#
# Release: This file is part of the kim-api-v1.6.3 package.
#


This directory (vc_forces_numer_deriv) contains a Verification Check that compares the
forces computed by a KIM-compliant Model with those obtained using numerical
differentiation of the Model energies.

Calling format:

   printf "model_name" | ./vc_forces_numer_deriv

Notes:

1. It generates its own KIM descriptor file in a string and uses
   kim_api_string_init to set up the KIM object.

2. It figures out which species a Model supports using
   KIM_API_get_model_species.

3. It checks a single configuration: a perturbed fcc cluster made of a random
   arrangement of the supported species with spacing scaled by a factor based
   on the Model's cutoff value.

4. The code supports the following NBCs:

        NEIGH_RVEC_H
        NEIGH_PURE_H
        NEIGH_RVEC_F
        NEIGH_PURE_F
        MI_OPBC_H
        MI_OPBC_F
        CLUSTER

   The code runs in sequence over all NBCs supported by the Model (from the
   above list).

5. The code computes the DIM*N components of the force vector in two ways:
   directly using the Model's force calculation (`force_model') and by
   numerical differentiation using Ridders' method (`force_numer').  The
   difference between these values in absolute value is also printed (`Force
   diff') as well as the error predicted by Ridders' method (`pred error').
   Ideally, one would expect the force difference to be less than the predicted
   error.  If that is the case the term `ok' is printed at the end of the
   line.  (Most potentials fail this check for most degrees of freedom, so this
   is not a good criterion.)

   In addition, the following normalized measure is computed:

   \alpha = 1/(DIM*N) sqrt( \sum_i w_i (f^{model}_i - f^{numer}_i)^2 / \sum_i w_i ),

   where w_i is the weight associated with term i:

   w_i = 1/\hat{\epsilon}_i,

   and \hat{\epsilon}_i is the normalized error in the numerical calculation:

   \hat{\epsilon}_i = max(\epsilon^{numer}_i, \epsilon^{prec}) /
                      max(\force^{numer}_i, \epsilon^{prec})

   The max functions impose a lower limit on computed values equal to the
   numerical precision of the computer (\epsilon^{prec}).

   \alpha has units of force and can be understood as the average error per
   degree of freedom.  The smaller the value of \alpha the more accurate the
   force calculation of the Model.

   In the expression for \alpha each term is weighted by the relative accuracy
   of the numerical estimate for the derivative.  Thus if f^{numer}_i is a poor
   estimate for the derivative (i.e. \epsilon^{numer}_i is large relative to
   f^{numer}_i) then term i contributes less to \alpha since it is less
   trustworthy.

   In addition to \alpha, the maximum term contributing to \alpha is
   identified.  For this degree of freedom, the error and normalized error are
   printed:

   forcediff_i = |f^{model}_i - f^{numer}_i}|

   forcediff_i/|f^{model}_i|

   This is *not* the largest error (i.e. the largest value of forcediff_i) due
   to the weighting term w_i.  Simply looking at the maximum value of
   forcediff_i could be misleading since the error in the numerical term,
   \epsilon^{numer}_i, may be large for the component.  Instead the maximum of
   w_i*forcediff_i is a compromise that in some sense seeks the largest error
   for components where the numerical derivative are also as accurate possible.


The following files are in the directory (before any compilation is performed):

LICENSE.CDDL
     The Common Development and Distribution License (CDDL) Version 1.0 file

Makefile
     Makefile to build executables with GNU or Intel compilers.

README
     This file.

vc_forces_numer_deriv.F03
     Fortran 2003 program that implements the Verification Check.
