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

This file provides an introduction to the openKIM API package.  This is the
first file that you should read after unpacking the package.

OVERVIEW:

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
atoms 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 being developed as part of the
Knowledgebase of Interatomic Models (KIM) project.  KIM (http://openKIM.org) 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 education, research, and industrial communities and to make it easier for
new (and existing) scientists to leverage the work of others in this important
field.  The KIM 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 OPENKIM-API PACKAGE:

The openkim-api package aims to give computer programmers the ability to write
atomistic or molecular simulation programs and routines capable of seamlessly
interfacing and interacting with other programs and routines, 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 openkim-api package is distributed under the PIs' (Ellad
B. Tadmor, Ryan S. Elliott, and James P. Sethna) copyright.  In the near
future, this package will be released under an open source license.
Discussions are currently underway in order to determine the appropriate type
of open source license.

The current version of the openkim-api package supports the following features:

* Currently supported programming languages: 
  C, C++, FORTRAN 77, Fortran 90/95.

  (Partial support for Fortran 2003 is available.  If you are interested in
  working with the openkim-api and Fortran 2003, please contact the developers
  at --- openkim@googlegroups.com --- and they will provide you with the latest
  development code and examples.)

* Support for static and dynamic linking of programs using the openKIM API

* 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 `Test' (simulation code that uses a Model).
  This is facilitated by the use of `KIM descriptor files' (terminated with a
  `.kim' extension) and a single KIM API object data structure that stores all
  information to be communicated between a Model and a Test.

* Data types: integer, integer*8 (long long), real (float), real*8 (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 Tests.

     Currently, the openkim-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 openkim-api supports the specification of physical units
  for each `argument' exchanged between a Model and Test.  Currently, this
  information is only used to ensure that a Model and Test agree on the units
  of the arguments they will exchange.  Future plans include the possibility of
  the openkim-api package performing automatic units conversions for Models and
  Tests that use different physical units, but are otherwise compatible.

* Neighbor lists and Boundary Conditions (NBC) methods: To facilitate
  computational efficiency, the openkim-api defines a number of standard
  methods by which a Test may provide a Model with information about the
  neighbors of each atom 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, `ghost atoms', and
  neighbor lists with relative position vectors.

* Neighbor list routines are expected to be provided by the calling Test.
  The API provides support for `Locator' and `Iterator' neighbor list modes.
  (A `Locator' returns the list of neighbors of a specified atom.  An `Iterator' 
  works by incrementing an atom counter and returning the identity of the next 
  atom (i.e. its number) and its neighbors.)  The API also supports half and full 
  neighbor lists.

* Atom Species: The openkim-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 such as CHARMM and similar force-fields will be added.

* Model Parameters: The openkim.org 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 openkim-api provides the ability
  for a Model to `publish' its parameters so that a Test may modify them during
  the course of a simulation.

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 openKIM API package.
See the detailed instructions in the INSTALL file in this directory.

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

This directory (by default, openkim-api-vX.X.X) contains the following files
and directories:

CHANGELOG
     list of main changes made to each API release

DOCs/
     documentation directory.  This directory contains the file
     openkim-api-introduction-vX.X.X.pdf which provides an overview of this
     release of the openkim-api package, links to the files
     KIMserviceDescriptions.txt and standard.kim, and a TEMPLATEs directory
     containing template files for creating your own KIM Models.  (See the
     README file in that directory.)

INSTALL
     detailed instructions on how to install the openKIM API package

KIM_API/
     directory containing the openkim-api service routines
        
MODELs/
     directory containing examples of interatomic Models

     Each Model is stored in its own directory that conforms to the naming
     convention specified in standard.kim.

Makefile
     make file for compiling the openkim-api services routines and example
     Tests and Models.

README
     This file.
 
TESTs/
     directory containing examples of Tests

     Each Test is stored in its own directory that conforms to the naming
     convention specified in standard.kim.

TODO
     A file listing features planed for future releases of the openKIM API


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

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.

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


