KIM Application Programming Interface (API)

Overview

The KIM API is an Application Programming Interface for atomistic simulations. The API provides a standard for exchanging information between atomistic simulation codes (molecular dynamics, molecular statics, lattice dynamics, Monte Carlo, etc.) and interatomic models (potentials or force fields). It also includes a set of library routines for using the API with bindings for:

  • FORTRAN 77, Fortran 90/95, Fortran 2003
  • C, C++

Atomistic simulation codes that support the KIM API work seamlessly with the KIM-compliant interatomic models (KIM Models) distributed on this website. The interface is computationally efficient and often requires relatively minor changes to existing codes. See here for a list of simulation codes that support the KIM API.

For details on KIM API features and what is included with the kim-api package, click here.


Installing the KIM API

In order to use KIM Models with a KIM-compliant simulation code, the first step is to install the KIM API. Note that the KIM API currently supports Unix/Linux and Mac OS systems. (MS Windows is not currently supported.)

Installation from source involves downloading the kim-api package, unpacking it, and following instructions to compile and install the code. The process requires a Unix/Linux or Mac OS system with GNU make and compilers and standard utilities.

  1. Download the latest version of the API:
    Download kim-api-v1.9.7.txz — released 2018/07/07
  2. Unpack the archive.

    • On Unix/Linux and Mac OS systems, type:

      $ tar Jxvf kim-api-v1.9.7.txz
      

      which will expand the archive into the directory ./kim-api-v1.9.7/

  3. Read the README file in the new directory.

  4. Read the NEWS file to see what is new in the current release.

  5. Install the package. (For complete instructions see INSTALL file.)

    • Quick start: try the following

       $ cd kim-api-v1.9.7
       $ ./configure
       $ make
       $ sudo make install
      

      (Make sure you know what you are doing when using sudo. Here, it should be safe.)

  6. Read the docs/README file for a step-by-step guide to learning the API.

Note: Installation from binary package is also possible in some cases. This involves installation of a pre-compiled binary package using standard package managers. It is currently only available for certain Linux/Unix systems. Click here for a list of systems for which binaries are available and installation instructions.


Installing KIM Models

Once the KIM API is installed, the next step is to install the KIM Models that are to be used with a KIM-compliant simulation code.

A "KIM Model" is an interatomic potential or force field that is compatible with the KIM API. KIM Models can be stand-alone or can be parameter files that are read in by a "KIM Model Driver".

The KIM API supports four "collections" of Models and Model Drivers. These are the "system-collection", the "user-collection", the "environment-variable-collection", and the "CWD-collection". This provides the user with flexibility on where Models and Model Drivers will be installed on their machine. See the INSTALL file in the kim-api package root directory for more information on collections.

The KIM API comes with the kim-api-v1-collections-management utility (available from version 1.9.0 on) to install and manage KIM Models. Dependencies on Model Drivers are automatically handled. For example, to install the Stillinger-Weber potential for silicon in the system collection do:

$ kim-api-v1-collections-management install system --sudo Three_Body_Stillinger_Weber_Si__MO_405512056662_003

Note that this model requires a Model Driver (Three_Body_Stillinger_Weber__MD_335816936951_002), which will also be automatically downloaded and installed.

To see the list of the Models and Model Drivers installed on the system do:

$ kim-api-v1-collections-management list

Type kim-api-v1-collections-management with no arguments, for a full list of supported options.


Using KIM Models

Once the KIM Models are installed, they can be used seamlessly with KIM-compliant simulation codes. See the documentation of the simulator of your choice for instructions.

As an example, instructions for using a KIM Model with the LAMMPS molecular dynamics package are available here. Once LAMMPS has been configured to use KIM, a KIM Model is used by specifying pair_style kim in the LAMMPS input script with the KIM Model identifier. For example, the following script computes the cohesive energy of the diamond structure using the Stillinger-Weber potential installed above:

# Generate a periodic diamond crystal and minimize the energy to obtain the
# equilibrium lattice constant and cohesive energy

# General
units           metal
boundary        p p p

# Define lattice, simulation box and crystal
lattice         diamond 5.4307
region          simbox block 0 1 0 1 0 1 units lattice
create_box      1 simbox
create_atoms    1 box

# Select potential and element
pair_style      kim KIMvirial Three_Body_Stillinger_Weber_Si__MO_405512056662_003
pair_coeff      * * Si
mass            1 28.0855

# Minimize energy to obtain relaxed configuration
fix             1 all box/relax iso 0.0 vmax 0.001
min_style       cg
minimize        1e-25 1e-25 5000 10000

# Compute equilibrium lattice constant and cohesive energy and print out
variable        natoms equal count(all)
variable        aeq equal vol^(1/3)
variable        Ec equal pe/v_natoms
print           "Equilibrium lattice constant (Angstrom) = ${aeq}"
print           "Cohesive energy (eV) = ${Ec}"

The only change in this file compared with using a built-in LAMMPS potential is the pair_style line defining the KIM Model.


KIM API Archive

The KIM API is under version control hosted at GitHub.

A detailed revision history is available here.

Older packaged versions of the KIM API source are available here


Getting Help

Support is always available by sending an email with a question and all relevant information to

openkim@googlegroups.com

The message will be posted to the openkim google group:

http://groups.google.com/group/openkim

Members of the OpenKIM development team actively monitor this forum and will do their best to respond to questions in a timely fashion. This forum is also used to announce minor new releases and bug fixes.

It is highly recommended for users who plan to work with the KIM API to become members of the openkim group. (Just go to the above link and click on "Join this group" on the right of the screen.)