#
# 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) 2012, Regents of the University of Minnesota.  All rights reserved.
#
# Contributors:
#
#    Mingjian Wen
#
#
# Release: This file is part of the openkim-api-v1.7.3 package.
#

This directory (Three_Body_Stillinger_Weber_MX2__MD_000000111111_000) contains three-body
Stillinger-Weber potential Model Driver for transition metal dichalcogenide monolayers
of the type MX2 (e.g. MoS2 and WSe2).


1. The functional form has been rewritten (from the original SW potential for silicon,
   see reference 1 below) so as to separate the potential parameters to avoid inconvenience
   of using this Model Dirver. The parameter `epsilon' in the standard SW potential is a
   dummy parameter, so it is combined with `A' and `lambda' in the 2-body term and 3-body
   term, respectively. The `cutoff' of the standard SW potential is determined implicitly
   by `cutoff = a*sigma', where `a' is a potential parameter. In this Model Driver,
   the `cutoff' is defined explicitly. By doing so, if `sigma' is updated through
   `PARAM_FREE_sigma' there is no needed to update `cutoff'.

   Above all, compared with the standard SW potential, the following redefinitions have
   been made:
     A      := A*epsilon
     lambda := lambda*epsion
     gamma  := gamma*sigma
     rcut   := a*sigma


2. Three-body bond angle bending is considered only for certain interations. Bond angle
   jik (i is the vertex atom at which bond ij and bond ik form the angle) is considered
   only when atoms j and k are of the same species, but different from the species of atom i.
   Explicitly, only bond angle of types spec2-spec1-spec2 and spec1-spec2-spec1 will
   contribute energy to the system. Besides the usual cutoffs rcut_ij and rcut_ik employed
   in the standard SW potential, additional cutoff rcut_jk is applied to bond jk. So, once
   either of the bond length rij, rik, or rjk is larger than its corresponding cutoff,
   the 3-body term vanishes (equals 0).


3. One parameter file is needed, and the parameters should be given as:

   First line: number of species (e.g. 2)

   Then each line lists the following 6 parameters for 2-body interaction (there should
   be 3 lines, for spec1-spec1, spec1-spec2, and spec2-spece2 interactions, respectively):
     A(in eV) B p q sigma(in Angstrom) rcut(in Angstrom)

   Then list the parameters in the 3-body term,
     lambda(in eV) rcut_jk(in Angstrom)  # for spec2-spec1-spec2 bond angle
     lambda(in eV) rcut_jk(in Angstrom)  # for spec1-spec2-spec1 bond angle
     gamma
     cos_theta0


The Model Driver complies with the KIM API standard, using four neihgbor handling methods:
MI_OPBC_F, NEIGH_PURE_F, NEIGH_RVEC_F, and CLUSTER and iterator or locator mode. It
publishes its parameters and supports optional computation of 'energy', 'forces',
'particleEnergy', 'process_dEdr', and 'process_dE2dr2'. Its initializaton routine takes
a KIM API object pointer and a pointer to a string that contains all parameters which
define a KIM Model based on this KIM Model Driver.


References:

1. F. H. Stillinger and T. A. Weber, "Computer simulation of local order in condensed
   phases of silicon", Phys. Rev. B, vol. 31, 5262-5271, 1985

2. Ellad B. Tadmor and Ronald E. Miller, Modeling Materials: Continuum, Atomistic and
   Multiscale Techniques, Cambridge University Press, 2011

3. Mingjian Wen, Sharmila N. Shirodkar, Petr Plechac, Efthimios Kaxiras, Ryan S. Elliott
   and Ellad B. Tadmor, "Stillinger-Weber potential for MoS2: parameterization and
   sensitivity analysis", Phys. Rev. B, in preparation, 2016


The following files are in this directory:

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

Three_Body_Stillinger_Weber_MX2.c
    C file that contains the implementation of the 3-body Stillinger-Weber potential
    Model Driver for MX2

Three_Body_Stillinger_Weber_MX2.kim.tpl
    Template KIM descriptor file containing all variables and methods that are
    exposed by the driver through the KIM API interface.  This file will be
    used (by the make system) to generate a KIM descriptor file for each KIM
    Model based on this Model Driver.