Fetching contributors…
Cannot retrieve contributors at this time
240 lines (188 sloc) 10.5 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
# Release: This file is part of the kim-api.git repository.
============================= The KIM API package =============================
This file provides an introduction to the KIM API package. This is the first
file that you should read after unpacking the package. See the INSTALL file
for instructions on how to build and install the package
Atomistic or molecular simulations of materials have the potential to play a
key role in the development of innovative technology to address many problems
the world is currently facing (including climate change, energy generation and
distribution, and terrorism). Recent examples, where valuable contributions
and greater insight have been obtained, include applications in chemistry and
organic chemistry, nanoindentation and tribology, materials processing and
properties, and nanotechnology and nanofluidics. To model the large numbers of
particles required for many applications, and to be able to study their
dynamics over reasonable time scales, it is generally necessary to develop
approximate models of interatomic bonding, referred to as "interatomic
potentials" or "interatomic models". Once such a model is at hand, one can in
principle predict almost any mechanical property (and some thermal properties)
of the element (or elements) it purports to describe. Generally, these models
define the forces and energies used for sophisticated simulations using
methodologies such as molecular dynamics, Monte Carlo, lattice dynamics free
energy methods, and multiscale methods. From such simulations, complex material
properties and phenomena can be extracted, including such things as melting
temperatures, solid-liquid interface phenomena, fracture properties, and
dislocation nucleation and motion.
This software package is an implementation of the application programming
interface (API) standard for interatomic models developed as part of the Open
Knowledgebase of Interatomic Models (OpenKIM) project. OpenKIM
( is a current initiative to develop and implement
standards for the atomistic simulation of materials. The effort aims to help
bring order to the efforts of the academic, research, and industry
communities and to make it easier for new (and existing) scientists to leverage
the work of others in this important field. The OpenKIM project has several
main objectives:
1. Development of an online open resource for standardized testing and
long-term warehousing of interatomic models (potentials and force fields)
and data.
2. Development of an API standard for atomistic simulations, which will allow
any interatomic model to work seamlessly with any atomistic simulation code.
3. Fostering the development of a quantitative theory of transferability of
interatomic models to provide guidance for selecting application-appropriate
models based on rigorous criteria, and error bounds on results.
4. Striving for the permanence of the KIM project, including development of a
sustainability plan, and establishment of a long-term home for its content.
The KIM API package is a system-level library that aims to give computer
programmers the ability to write atomistic or molecular simulation programs
that can seamlessly interface with implementations of interatomic models,
regardless of the programming language (C, C++, FORTRAN 77, Fortran 90/95/2003,
Python, etc.) in which the codes are written.
This version of the KIM API package is distributed under the CDDL Open Source
The current version of the KIM API package supports the following features:
* Currently supported programming languages:
C, C++, FORTRAN 77, Fortran 90/95, Fortran 2003.
* Support for automatic translation between zero-based lists (C-style numbering
beginning with 0) and one-based lists (Fortran-style numbering beginning
with 1)
* Communication of an arbitrary number of `arguments' between a `Model'
(interatomic potential) and a `Simulator' (simulation code that uses a
Model). This is facilitated by the use of `KIM descriptor files' (whose
names end with a `.kim' extension) and a single KIM API object data structure
that stores all information to be communicated between a Model and a
* Data types: integer, float, double, method (for exchanging pointers to
functions), pointer (for exchanging "everything else"). Each of
these data types can be use to create multi-dimensional array
`arguments' that are exchanged between Models and Simulators.
Currently, the KIM API does not define any (more complex) data structures.
However, in the future (as the need arises, and in consultation with the
atomistic and molecular simulation community) additional data types and
data structures may be introduced.
* Physical Units: The KIM API supports the specification of physical units for
each `argument' exchanged between a Model and Simulator. A Model is either
`fixed' or `flexible' with regard to units. `fixed' means it is unable to
convert to a different set of units. `flexible' means it can convert its
values to the Simulator's units.
* (deprecated) Neighbor lists and Boundary Conditions (NBC) methods: To
facilitate computational efficiency, the KIM API defines a number of standard
methods by which a Simulator may provide a Model with information about the
neighbors of each particle in a configuration. These currently include
options that allow for common techniques, such as the use of the `minimum
image' convention for orthogonal periodic boundary conditions, `padding
particles', and neighbor lists with relative position vectors and `image
* Neighbor list routines are expected to be provided by the calling Simulator.
The API provides support for `Locator' and (deprecated) `Iterator' neighbor
list modes. (A `Locator' returns the list of neighbors of a specified
particle. An (deprecated) `Iterator' works by incrementing a particle
counter and returning the identity of the next particle (i.e. its number) and
its neighbors.) The API also supports (deprecated) half (symmetric and
unsymmetric) and full neighbor lists.
* Particle Species: The KIM API provides the ability to designate the physical
species of each particle in a simulation. Currently, only one identifier is
provided for each element in the periodic table. In the future support for
Models that require multiple types of each element will be added.
* Model Parameters: The OpenKIM philosophy views a `Model' as a well-defined
computational code that includes fixed specific values for all parameters
needed to perform an actual computation. However, it is often useful to
explore how a Model's predictions vary as the values of its parameters are
varied. For this reason, the KIM API provides the ability for a Model to
`publish' its parameters so that a Simulator may modify them during the
course of a simulation.
* Model Drivers: The KIM API package provides the ability to create Model
Driver routines. 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 more information on all of the above, see the files in the docs directory
described below. Features planned for future releases are described in the
TODO file in this directory. (See list of directory contents below.)
Your next step after reading this file is to install the KIM API package. See
the detailed instructions in the INSTALL file in this directory.
This directory (by default, kim-api-vX.Y.Z) contains the following files and
A set of detailed instructions on how to install the KIM API package.
The Common Development and Distribution License (CDDL) Version 1.0 file.
Makefile for compiling the KIM API library and examples.
Example Makefile.KIM_Config file. This file provides the basic settings
needed to build the KIM API system and associated Model Drivers, Models,
and the provided examples.
Makefile containing variable definitions for the complete SemVer version
of the KIM API package.
A list of main changes made for each KIM API release.
This file.
A file listing features planed for future releases of the KIM API package.
A directory containing the common Makefiles and default settings used by
the KIM API package build system.
A shell script to configure the KIM API and create a Makefile.KIM_Config
Documentation directory. This directory contains the file
kim-api-vX.Y.Z-introduction.pdf which provides an overview of this release
of the KIM API package, the file KIM_API_Descriptions.txt, a link to the
file, and a templates directory containing template files for
creating your own KIM Models. (See the README file in that directory.)
A directory containing examples of interatomic Model Drivers, Models,
Simulators, and OpenKIM Tests.
A directory containing the KIM API source code.
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.