=========================== The openkim-api package ===========================

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


STEP 0

   It you have not already done so, read the README file in the API root
   directory, referred to as $KIM_DIR (by default: openkim-api-vX.X.X/), and
   follow the instructions in the INSTALL file in the same directory to install
   the openKIM API package.


STEP 1

   Read openkim-api-introduction-vX.X.X.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 openKIM API.


STEP 2

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

   $KIM_DIR/MODELs/EXAMPLES.README
   $KIM_DIR/TESTs/EXAMPLES.README

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


STEP 3

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

   % cd $KIM_DIR/TESTs
   % ./run_all_tests > run_all_tests.out

   The above command redirects the output to the file `run_all_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):

   % echo "model_Ar_P_MLJ_C" | $KIM_DIR/TESTs/test_Ar_free_cluster/test_Ar_free_cluster

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


STEP 4

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

   The list of Models and Tests is given in $KIM_DIR/MODELs/EXAMPLES.README and
   $KIM_DIR/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

   test_Ar_free_cluster_CLUSTER_C

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

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

   $KIM_DIR/TESTs/test_Ar_free_cluster_CLUSTER_C/test_Ar_free_cluster_CLUSTER_C.c
   $KIM_DIR/TESTs/test_Ar_free_cluster_CLUSTER_C/test_Ar_free_cluster_CLUSTER_C.kim

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

   $KIM_DIR/DOCs/KIMserviceDescription.txt
   $KIM_DIR/DOCs/standard.kim

   The first file, `KIMserviceDescription.txt', is a reference file which
   explains the functioning of the different KIM API service 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

   model_Ar_P_MLJ_CLUSTER_C

   which is written in C.  (The same program written in Fortran 90, called
   `model_Ar_P_MLJ_CLUSTER_F90', is also provided.)  This is a modified
   Lennard-Jones potential written in Fortran 90 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 computer code for this Model and corresponding KIM descriptor file are
   located in

   $KIM_DIR/MODELs/model_Ar_P_MLJ_CLUSTER_C/model_Ar_P_MLJ_CLUSTER_C.c
   $KIM_DIR/MODELs/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 `KIMserviceDescription.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.


STEP 5

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

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

   $KIM_DIR/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:

openkim-api-introduction-vX.X.X.pdf 
     presentation file describing the concepts on which the openkim-api system
     is based.

KIMserviceDescription.txt
     A link to the file in ../KIM_API which describes the openkim-api functions.

README
     This file.

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

standard.kim
     A link to the file in ../KIM_API which describes the openkim-api descriptor
     file format and contents.

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

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.

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