KIM Application Programming Interface (API)


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, see the documentation 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-2.0.2.txz — released 2019/03/28
  2. Unpack the archive.

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

      $ tar Jxvf kim-api-2.0.2.txz

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

  3. Read the 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-2.0.2
       $ mkdir build
       $ cd build
       $ cmake .. -DCMAKE_BUILD_TYPE=Release
       $ make
       $ sudo make install
       $ sudo ldconfig

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

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-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-collections-management install system --sudo SW_StillingerWeber_1985_Si__MO_405512056662_005

Note that this model requires a Model Driver (SW__MD_335816936951_004), 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-collections-management list

Type kim-api-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 SW_StillingerWeber_1985_Si__MO_405512056662_005
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 documentation for developers

Documentation for the latest developent git branch is available here:

Documentation for the latest KIM API release is available here:

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

The message will be posted to the openkim google group:

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.)