#
# 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:
#    Ryan S. Elliott
#    Ellad B. Tadmor
#    Valeriu Smirichinski
#

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


============================= The KIM API package =============================

This file provides a guide to the material provided with the KIM API package.
It suggests an order for reading the various documentation and code files to
facilitate the learning process.


STEP 0

   If you have not already done so, read the README file in the KIM API root
   directory, referred to as ${KD} (by default: kim-api-vX.Y.Z), and follow the
   instructions in the INSTALL file in the same directory to install the KIM
   API package.


STEP 1

   Read kim-api-vX.Y.Z-introduction.pdf which is located in the docs directory
   (same directory as this file).  This pdf file contains a presentation
   providing an overview of the OpenKIM project and basic concepts related to
   the KIM API.


STEP 2

   The KIM API package comes with a number of example Models (interatomic
   potentials) and Simulators and OpenKIM Tests (simulation codes) which
   demonstrate how the API works.  Read about the provided Models, Simulators,
   and Tests in these files:

   ${KD}/examples/models/EXAMPLES.README
   ${KD}/examples/openkim_tests/EXAMPLES.README
   ${KD}/examples/simulators/EXAMPLES.README

   These files include a list of the Models, Simulators, and Tests and brief
   descriptions of what they do.

   From now on we will assume you have performed the `make' and `make examples'
   build steps.


STEP 3

   Included with the package is a script that runs all of the possible
   combinations of Models and OpenKIM Tests (see
   ${KD}/openkim_tests/EXAMPLES.README for the list of Model/Test
   compatibilities).  Run this script:

   % cd ${KD}/examples/openkim_tests
   % ./run_all_ex_tests > run_all_ex_tests.out 2>&1

   The above command redirects the output to the file `run_all_ex_tests.out'.
   Look over this file to see what the output generated by the different Tests
   looks like.  To run an individual Test/Model combination by yourself from
   the command line, you can type (for example):

   % cd ${KD}/examples/openkim_tests/ex_test_Ar_free_cluster
   % printf "ex_model_Ar_P_MLJ_C" | ./ex_test_Ar_free_cluster

   which will run the Test `ex_test_Ar_free_cluster' with the
   `ex_model_Ar_P_MLJ_C' Model.  In this case, this is a Test written in
   Fortran 2003 running a modified Lennard-Jones potential for Ar written in C.


STEP 4

   Now that we have seen some examples of the KIM API in operation, the next
   step is to understand how it works.  This is the stage where we need to
   start looking at source code.

   The list of Models and OpenKIM Tests is given in
   ${KD}/examples/models/EXAMPLES.README and
   ${KD}/examples/openkim_tests/EXAMPLES.README, respectively.  Each of those
   files includes a brief description of the Models/Tests in order of
   increasing complexity and noting the programming language.  For example, the
   simplest Test is

   ex_test_Ar_free_cluster_CLUSTER_C

   which is written in C.  (The same program written in Fortran 2003 called
   `ex_test_Ar_free_cluster_CLUSTER_F03' is also provided.)  This test computes
   the energy and forces on the particles of an isolated cluster of Ar
   particles arranged in a face-centered cubic (FCC) structure.  The Tests do
   not provide neighbor list handling.  The called Model must loop over all
   particles to find the neighbors of a given particle.

   The source code for this Model and corresponding KIM descriptor file are
   located in

   ${KD}/examples/openkim_tests/ex_test_Ar_free_cluster_CLUSTER_C/ex_test_Ar_free_cluster_CLUSTER_C.c
   ${KD}/examples/openkim_tests/ex_test_Ar_free_cluster_CLUSTER_C/descriptor.kim

   Read through these two files (or the corresponding files for the Fortran
   Test).  As you read, you can refer to the following files:

   ${KD}/docs/KIM_API_Description.txt
   ${KD}/docs/standard.kim

   The first file, `KIM_API_Description.txt', is a reference file which
   explains the functioning of the different KIM API library routines which are
   called by the Test code.  The second file, `standard.kim', explains the
   lines that appear in the KIM descriptor file.

   After reading and understand the above Test, study a simple Model.  The
   simplest Model is

   ex_model_Ar_P_MLJ_CLUSTER_C

   which is written in C.  (The same program written in Fortran 2003, called
   `ex_model_Ar_P_MLJ_CLUSTER_F03', is also provided.)  This is a modified
   Lennard-Jones potential for Ar (here "modified" reflects the fact that a
   quadratic function is added to the Lennard-Jones potential to obtain a
   smooth cutoff).  The Model only works with the `CLUSTER' neighbor list and
   boundary condition (NBC) method which does not use neighbor list
   information.

   The source code for this Model and corresponding KIM descriptor file are
   located in

   ${KD}/examples/models/ex_model_Ar_P_MLJ_CLUSTER_C/ex_model_Ar_P_MLJ_CLUSTER_C.c
   ${KD}/examples/models/ex_model_Ar_P_MLJ_CLUSTER_C/model_Ar_P_MLJ_CLUSTER_C.kim

   Read through these files (or the corresponding files for the Fortran Model)
   referring to `KIM_API_Description.txt' and `standard.kim' as explained
   above.

   Once you understand how the simple Test and Model described above work,
   continue working down the list of Tests and Models in the EXAMPLES.README
   files exploring code of increasing complexity.

   At the end of the list of Models in ${KD}/examples/models/EXAMPLES.README,
   you will find several Models that are generated from Model Drivers.  A Model
   Driver is an implementation of a Model class (as opposed to a particular
   instance of a Model).  A Model for a given material can be created from a
   Model Driver by providing a file (or files) with the appropriate parameter
   values for the material of interest.  For example, the Lennard-Jones
   potential is a Model class.  Particular instances of the Lennard-Jones model
   for a given material are obtained once the Lennard-Jones parameters (sigma,
   epsilon and cutoff radius) are specified.  Model Drivers are handled
   differently than Models within the KIM API package.  Example Model Drivers
   are stored separately within the ${KD}/examples/model_drivers directory.
   Read the EXAMPLES.README within that directory for a description of the
   existing Model Drivers.  Every Model generated from a Model Driver will have
   its own directory under ${KD}/examples/models just like a regular KIM Model.
   However, the contents of the directory will be different.  First, the
   `Makefile' will be different.  It will contain the name of the associated
   Model Driver routine along with additional information.  Second, instead of
   a code file containing the implementation of the Model, there will be a data
   file (or files), whose name(s) is(are) listed in the Makefile, containing
   the parameters to be read in by the Model Driver.  (See the README file in
   the corresponding Model Driver directory under ${KD}/examples/model_drivers
   for a description of the parameters and expected format.)  To understand how
   the Model works, study the code of the Model Driver which is stored in the
   appropriate directory under ${KD}/examples/model_drivers.  Also, after
   compiling the Model, read the C++ file parameterized_model.cpp.  This file
   is generated by the KIM API build system and implements the connection
   between the Model and its Model Driver.  (If you can't find the file run
   `make parameterized_model.cpp' and it will be generated.)


STEP 5

   At this stage, you are ready to create a new KIM-Compliant Model of your
   own.  To facilitate this process, the KIM API package includes template
   files for both Models and Model Drivers which can be readily modified to
   create new Models and Model Drivers.

   A description of the templates and directions for how to use them to create
   a new KIM-Compliant model are given in

   ${KD}/docs/templates/README

   Read this file and then follow the instructions to create a new
   KIM-Compliant pair potential.  As a particular example, create a
   KIM-Compliant Buckingham potential for Ar.

   The functional form of the Buckingham potential is

   phi(r) = A Exp(-r/rho) - C/r^6

   where A, rho and C are parameters.  For Ar these parameters are:

   A   = 10548.1515 eV
   rho = 0.273 angstrom
   C   = 63.6633994 eV*angstrom^6

   Ref: Equation (27) in

        R. A. Buckingham, "The classical equation of state of gaseous helium,
        neon and argon", Proc. R. Soc. Lond. A, vol 168, 264-283, 1938.

   Another template is provided for pair functional models.  (`Pair
   functionals' is the generic name for embedded-atom method (EAM),
   Finnis-Sinclair, Effective Medium Theory, and glue potentials that all have
   the same abstract functional form.)

   You should now be ready to create new KIM-Compliant Models of arbitrary
   form.

-------------------------------------------------------------------------------

This directory contains the following files and directories:

KIM_API_Description.txt
     Description of KIM API library routines.

README
     This file.

kim-api-vX.Y.Z-introduction.pdf
     Presentation file describing the concepts on which the KIM API system is
     based.

standard.kim
     A link to the file in ../src which defines and describes the KIM API
     descriptor file format and contents.

templates/
     Directory containing templates and instructions for creating your own KIM
     Model Drivers and Models.

*******************************************************************************

SUPPORT

If you have problems or questions, send an email with your question and all
relevant information to

openkim@googlegroups.com

The members of the OpenKIM development team actively monitor this email list
and will do their best to help you with your question in a timely fashion.

*******************************************************************************
