#
# 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--2015, Regents of the University of Minnesota.
# All rights reserved.
#
# Contributors:
#    Ryan S. Elliott
#


This directory (EAM_CubicNaturalSpline__MD_853402641673_000) contains an
EAM Model Driver which reads Dynamo setfl, funcfl, and setfl Finnis Sinclair 
table files.  The driver is written in C++.  The driver is designed to 
mimic/reproduce the behavior of LAMMPS's eam, eam/alloy, and eam/fs pair_styles. 
The type of table file provided is automatically detected.

This Model Driver complies with the KIM API interface standard, using any NBC
and iterator or locator mode, publishes its parameters, and supports optional
computation of `energy', `forces', `particleEnergy', `process_dEdr', and
`process_d2Edr2'.  Its initialization routine takes a KIM API object pointer, a
pointer to a two-dimensional character array (each row of which contains the
full path to a parameter file) of the form a[b][c], a pointer to the value of
c, and a pointer to the value of b.  This Model Driver expects b > 1 when
multiple funcfl files are used to define a multi-species Model.  Otherwise, it
expects b = 1.  In this case it determines the type of provided table file by
the file's contents.

The format of the Dynamo files supported by this Model Driver follows the
LAMMPS format.  (NOTE an exception: To facilitate auto-detection of table file
type, all floating point values are expected to be proper floating point
numbers, with at least a decimal point.  This is required in order to
distinguish them from integer values.)  The LAMMPS format is described below
(adapted from the LAMMPS documentation as of 2013-11-19):

This Model Driver computes pairwise interactions for metals and metal alloys
using embedded-atom method (EAM) potentials (Daw). The total energy Ei of an
atom I is given by

     E_i = F_\alpha( \sum_{j\neq i} \rho_\beta(r_{ij})) 
           + (1/2)\sum_{j\neq i} \phi_{\alpha \beta}(r_{ij})



A DYNAMO single-element funcfl file is formatted as follows:

* line 1: comment (ignored)
* line 2: atomic number, mass, lattice constant, lattice type (e.g. FCC)
* line 3: Nrho, drho, Nr, dr, cutoff

The mass is in mass units, e.g. mass number or grams/mole for metal units. The
cubic lattice constant is in Angstroms.  On line 3, Nrho and Nr are the number
of tabulated values in the subsequent arrays, drho and dr are the spacing in
density and distance space for the values in those arrays, and the specified
cutoff becomes the pairwise cutoff for the potential.  The units of dr are
Angstroms; I'm not sure of the units for drho - some measure of electron
density.

Following the three header lines are three arrays of tabulated values:

* embedding function F(rho) (Nrho values)
* effective charge function Z(r) (Nr values)
* density function rho(r) (Nr values)

The values for each array can be listed as multiple values per line, so long as
each array starts on a new line.  For example, the individual Z(r) values are
for r = 0.0,dr,2*dr, ... (Nr-1)*dr.

The units for the embedding function F are eV. The units for the density
function rho are the same as for drho (see above, electron density).  The units
for the effective charge Z are "atomic charge" or sqrt(Hartree * Bohr-radii).
For two interacting atoms i,j this is used to compute the pair potential term
in the EAM energy expression as r*phi, in units of eV-Angstroms, via the
formula

r*phi = 27.2 * 0.529 * Zi * Zj 
where 1 Hartree = 27.2 eV and 1 Bohr = 0.529 Angstroms.



A DYNAMO multi-element setfl file is formatted as follows:

* lines 1,2,3 = comments (ignored)
* line 4: Nelements Element1 Element2 ... ElementN
* line 5: Nrho, drho, Nr, dr, cutoff

In a DYNAMO setfl file, line 4 only lists Nelements = the # of elements in the
setfl file.  The element name (Ni, Cu, etc) of each element must be included on
the line, in the order the elements appear in the file.

The meaning and units of the values in line 5 is the same as for the funcfl
file described above.  Note that the cutoff (in Angstroms) is a global value,
valid for all pairwise interactions for all element pairings.

Following the 5 header lines are Nelements sections, one for each element, each
with the following format:

* line 1 = atomic number, mass, lattice constant, lattice type (e.g. FCC)
* embedding function F(rho) (Nrho values)
* density function rho(r) (Nr values)

The cubic lattice constant is in Angstroms. The F and rho arrays are unique to
a single element and have the same format and units as in a funcfl file.

Following the Nelements sections, Nr values for each pair potential phi(r)
array are listed for all i,j element pairs in the same format as other arrays.
Since these interactions are symmetric (i,j = j,i) only phi arrays with i >= j
are listed, in the following order: i,j = (1,1), (2,1), (2,2), (3,1), (3,2),
(3,3), (4,1), ..., (Nelements, Nelements).  Unlike the effective charge array
Z(r) in funcfl files, the tabulated values for each phi function are listed in
setfl files directly as r*phi (in units of eV-Angstroms), since they are for
atom pairs.



A DYNAMO Finnis Sinclair setfl file is formatted as follows:

In this case the Model Driver computes pairwise interactions for metals and
metal alloys using a generalized form of EAM potentials due to Finnis and
Sinclair (Finnis). The total energy Ei of an atom I is given by

     E_i = F_\alpha( \sum_{j\neq i} \rho_{\alpha \beta}(r_{ij})) 
           + (1/2)\sum_{j\neq i} \phi_{\alpha \beta}(r_{ij})

These files include more information than the DYNAMO setfl format files
described above, in that i,j density functionals for all pairs of elements are
included as needed by the Finnis/Sinclair formulation of the EAM.

* lines 1,2,3 = comments (ignored)
* line 4: Nelements Element1 Element2 ... ElementN
* line 5: Nrho, drho, Nr, dr, cutoff

The 5-line header section is identical to an EAM setfl file.

Following the header are Nelements sections, one for each element I, each with
the following format:

* line 1 = atomic number, mass, lattice constant, lattice type (e.g. FCC)
* embedding function F(rho) (Nrho values)
* density function rho(r) for element I at element 1 (Nr values)
* density function rho(r) for element I at element 2
* ...
* density function rho(r) for element I at element Nelement

The units of these quantities in line 1 are the same as for setfl files. Note
that the rho(r) arrays in Finnis/Sinclair can be asymmetric (i,j != j,i) so
there are Nelements^2 of them listed in the file.

Following the Nelements sections, Nr values for each pair potential phi(r)
array are listed in the same manner (r*phi, units of eV-Angstroms) as in EAM
setfl files.  Note that in Finnis/Sinclair, the phi(r) arrays are still
symmetric, so only phi arrays for i >= j are listed.

Natural cubic spline is used to interpolate the tabulated potential data. 
This spline requires second derivatives at both ends to be zero, and first 
and second derivatives to be continuous at each internal knot. 

The contents of the directory are as follows (before any compilation is
performed):


CreateDispatch.sh
     Bash shell script used to generate, at compile time, a C++ switch
     statement that calls the correct templated version of the EAM
     compute function.

EAM.cpp
     Implementation of Model Driver interface consisting of wrapper functions
     that call the corresponding member functions of the implementation object.

EAM.hpp
     Header file for the (minimal) Model Driver interface.  Here we use the
     "pointer to implementation" (pimpl) pattern to hide all implementation
     details.

EAM.kim.tpl
     KIM descriptor template file, contains all variables and methods that are
     exposed through the KIM API interface

EAM_CubicNaturalSpline.hpp
     defines for a natural cubic spline interpolation and evaluation

EAM_CubicNaturalSpline.cpp
     Implementation of SplineInterpolate for the natural cubic spline.

EAM_Implementation.cpp
     Actual implementation of the EAM driver code.

EAM_Implementation.hpp
     Header file for implementation of EAM.  Includes definition of the
     compute function since this is templated in order to provide the highest
     possible computational efficiency.

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

Makefile
     Makefile to compile and build executables with GNU or Intel compilers

README
     This file

kimspec.edn
     File containing metadata needed by the OpenKIM webapp.