#
# 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--2018, Regents of the University of Minnesota.
# All rights reserved.
#
# Contributors:
#    Ellad B. Tadmor
#    Ryan S. Elliott
#    Toon Verstraelen
#

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


This directory (utility_forces_delta) contains a utility that tests the forces
by computing the energy difference between two distorted structures and
comparing this to a clever first-order estimate of the difference.  The
first-order estimate is constructed such that second order terms nearly vanish.
This utility is derived from utility_forces_numer_deriv.

Calling format:

   printf "model_name" | ./utility_forces_delta

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_partcl_typs.

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. For each NBC, 100 displacements are computed. At the reference point and at
   the displaced point, the energy and the forces are computed.  The difference
   in energy is then compared to an estimate of this difference based on the
   forces at both points:

      delta = energy1 - energy2
      delta_estimated = dot(force1+force2, disp)/2
      error = delta - delta_estimated

   One can show that the estimate is correct up to second order if the energy
   is a well-behaved function of the coordinates.  Hence, the estimate is not
   too sensitive to the magnitude of the displacements.

   The mean absolute error and the mean absolute delta are computed.  The ratio
   between the two parameters is computed and should be of the order of 1.0E-8
   (if the forces were implemented correctly).



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.

utility_forces_delta.F03
     Fortran 2003 program that implements the utility.
