Fetching contributors…
Cannot retrieve contributors at this time
270 lines (199 sloc) 10.7 KB
# 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
# 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.
# 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.git repository.
============================= 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.
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.
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.
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:
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.
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.
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
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
Read through these two files (or the corresponding files for the Fortran
Test). As you read, you can refer to the following files:
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, `', 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
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
The source code for this Model and corresponding KIM descriptor file are
located in
Read through these files (or the corresponding files for the Fortran Model)
referring to `KIM_API_Description.txt' and `' as explained
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.)
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
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
This directory contains the following files and directories:
Description of KIM API library routines.
This file.
Presentation file describing the concepts on which the KIM API system is
A link to the file in ../src which defines and describes the KIM API
descriptor file format and contents.
Directory containing templates and instructions for creating your own KIM
Model Drivers and Models.
If you have problems or questions, send an email with your question and all
relevant information to
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.