KIM Application Programming Interface (API)

Download kim-api-v1.9.2.txz — released 2017/10/08

Visit the OpenKIM Forum on Google Groups for assistance.

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++

By conforming to this API, an atomistic simulation code will seamlessly work with any KIM-compliant interatomic model written in any supported language. The interface is computationally efficient and often requires relatively minor changes to existing codes.

Details about the latest release and installation instructions are available here.


What is in the KIM API source package?

The current version of the kim-api package includes the API itself and the following example codes:

Models

(for more information see the file $(KIM_DIR)/examples/example_legos/model_legos/README)

  • Lennard-Jones pair potential shifted to zero energy at cutoff.
    • Parameterized for Ar and Ne (ex_model_Ar_P_LJ, ex_model_Ne_P_LJ)
    • An implementation for Ne that is optimized for computational speed (ex_model_Ne_P_fastLJ)
    • An implementation for Ne that demonstrates the use of F77 with the api (ex_model_Ne_P_LJ_NEIGH_PURE_H)
  • Lennard-Jones pair potential with quadratic cutoff function.
    • Parameterized for Ar and Ne. (ex_model_Ar_P_MLJ_C, ex_model_Ar_P_MLJ_CLUSTER_C, ex_model_Ar_P_MLJ_CLUSTER_F03, ex_model_Ar_P_MLJ_F03, ex_model_Ar_P_MLJ_MI_OPBC_H_F, ex_model_Ar_P_MLJ_NEIGH_PURE_H_F, ex_model_Ar_MLJ_NEIGH_RVEC_F, ex_model_Ne_P_MLJ_NEIGH_RVEC_F)
    • Note: multiple versions of this potential are provided in order to demonstrate the various features and options of the api.
  • Morse pair potential shifted to zero energy at cutoff.
    • Parameterized for Ar and Ne (ex_model_Ar_P_Morse, ex_model_Ne_P_Morse)
  • Lennard-Jones alloy pair potential with quadratic cutoff function.
    • Parameterized for ArNe alloys (ex_model_ArNe_P_MLJ_NEIGH_RVEC_F)
  • Ercolessi Adams EAM potential for Al (ex_model_Al_PF_ErcolessiAdams)

  • Johnson EAM potential for Cu (ex_model_Cu_PF_Johnson)

Tests

(for more information see the file $(KIM_DIR)/examples/example_legos/openkim_test_legos/README)

  • Compute the energy and forces on a finite chunk of an fcc crystal. Versions for Al, Ar and Ne are provided. (ex_test_Al_free_cluster, ex_test_Ar_free_cluster, ex_test_Ar_free_cluster_CLUSTER_C, ex_test_Ar_free_cluster_CLUSTER_F03, ex_test_Ne_free_cluster, ex_test_Ne_free_cluster_SI, ex_test_Ne_free_cluster_stiff)
    • The ex_test_Ne_free_cluster_SI and ex_test_Ne_free_cluster_stiff versions use the SI unit system and compute the Hessian for the cluster, respectively.
  • Compute the relaxed lattice spacing and cohesive energy of a periodic infinite fcc crystal of Al, Ar, and Ne. (ex_test_Al_FCCcohesive_MI_OPBC, ex_test_Ar_FCCcohesive_MI_OPBC, ex_test_Ar_FCCcohesive_NEIGH_PURE, ex_test_Ar_FCCcohesive_NEIGH_RVEC)

  • Compute the relaxed lattice spacing and cohesive energy of a periodic infinite B2 crystal of ArNe. (ex_test_ArNe_periodic_B2_NEIGH_RVEC)

  • Compute the relaxed lattice spacing and cohesive energy of a periodic infinite fcc crystal of Ar for a variety of Model cutoff values. (ex_test_Ar_FCCcohesiveCutoff_NEIGH_RVEC)

  • Compute energy and forces for two models in one Test (ex_test_Ar_multiple_models) This Test is meant to illustrate some more advanced usage of the api.

Verification Checks

  • Perform a smart numerical derivative of the energy and compare the results to the forces. (vc_forces_numer_deriv)

Obtaining the KIM API and KIM Models

The KIM API and KIM Models can be obtained in either binary package form (for some systems) or for installation from source. Details on the systems for which binaries are available and information on installing from source are given below.

Ubuntu (version Vivid 15.04 and Trusty 14.04 LTS) binary packages

For Ubuntu systems, there are separate binary packages available for the KIM API and each KIM Model available from OpenKIM. There is also a package that allows for the installation of all KIM Models available from OpenKIM in one step.

You need to install the KIM API and then install any KIM Models from OpenKIM you are interested in using.

To install the KIM API (this installs the API system-wide and requires root access)

$ sudo add-apt-repository ppa:openkim/openkim
$ sudo apt-get update
$ sudo apt-get install kim-api


To get a list of the available Ubuntu packages for KIM Models from OpenKIM

$ apt-cache search openkim


To get information about any particular package use apt-cache show. For example

$ apt-cache show openkim-mo-947112899505-001


To install a single KIM Model from OpenKIM use apt-get install. For example

$ sudo apt-get install openkim-mo-947112899505-001


To install all KIM Models available from OpenKIM

$ sudo apt-get install openkim-v1-all

CentOS (version 6 and 7) binary packages

For CentOS systems, there are separate binary packages available for the KIM API and each KIM Model available from OpenKIM. There is also a package that allows for the installation of all KIM Models available from OpenKIM in one step.

You need to install the KIM API and then install any KIM Models from OpenKIM you are interested in using.

To install the KIM API (this installs the API system-wide and requires root access)

$ sudo yum update
$ wget https://packages.openkim.org/rpm/centos/openkim-centos-rhel-repo-1-2.noarch.rpm
$ sudo rpm -i openkim-centos-rhel-repo-1-2.noarch.rpm
$ sudo yum update
$ sudo yum install kim-api


To get a list of the available CentOS packages for KIM Models from OpenKIM

$ yum list "openkim-mo-*"


To get information about any particular package use yum info. For example

$ yum info openkim-mo-947112899505-001


To install a single KIM Model from OpenKIM use yum install. For example

$ sudo yum install openkim-mo-947112899505-001


To install all KIM Models available from OpenKIM

$ sudo yum install openkim-v1-all

Fedora (version 22) binary packages

For Fedora systems, there are separate binary packages available for the KIM API and each KIM Model available from OpenKIM. There is also a package that allows for the installation of all KIM Models available from OpenKIM in one step.

You need to install the KIM API and then install any KIM Models from OpenKIM you are interested in using.

To install the KIM API (this installs the API system-wide and requires root access)

$ sudo dnf update
$ wget https://packages.openkim.org/rpm/fedora/openkim-fedora-repo-1-2.noarch.rpm
$ sudo rpm -i openkim-fedora-repo-1-2.noarch.rpm
$ sudo dnf update
$ sudo dnf install kim-api


To get a list of the available Fedora packages for KIM Models from OpenKIM

$ dnf list "openkim-mo-*"


To get information about any particular package use dnf info. For example

$ dnf info openkim-mo-947112899505-001


To install a single KIM Model from OpenKIM use dnf install. For example

$ sudo dnf install openkim-mo-947112899505-001


To install all KIM Models available from OpenKIM

$ sudo dnf install openkim-v1-all

openSUSE (version 42.1) binary packages

For openSUSE systems, there are separate binary packages available for the KIM API and each KIM Model available from OpenKIM. There is also a package that allows for the installation of all KIM Models available from OpenKIM in one step.

You need to install the KIM API and then install any KIM Models from OpenKIM you are interested in using.

To install the KIM API (this installs the API system-wide and requires root access)

$ sudo zypper update
$ sudo zypper ar -t rpm-md -f -G -c https://packages.openkim.org/rpm/opensuse/42.1/x86_64 openkim
$ sudo zypper update
$ sudo zypper install kim-api


To get a list of the available openSUSE packages for KIM Models from OpenKIM

$ zypper search "openkim-mo-*"


To get information about any particular package use zypper info. For example

$ zypper info openkim-mo-947112899505-001


To install a single KIM Model from OpenKIM use zypper install. For example

$ sudo zypper install openkim-mo-947112899505-001


To install all KIM Models available from OpenKIM

$ sudo zypper install openkim-v1-all


Other binary packages

Coming soon…


MacOS X source/binary packages

Coming soon…


Download the KIM API source

The most recent packaged download of the KIM API is available here:

Download kim-api-v1.9.2.txz — released 2017/10/08

Details about the latest release and installation instructions are available here.

Our API is under version control hosted at GitHub.


Older packaged versions of the KIM API source

Click here to view a detailed listing of previous versions.




OpenKIM Boot Camp: Learning about the OpenKIM system

The OpenKIM system and the KIM API are not difficult to use but they involve new concepts and require some training. For users interested in contributing to the OpenKIM system (by writing and uploading Models, Tests or Visualizers and/or creating and uploading Reference Data), we recommend the following training:

  1. Setup a working OpenKIM Virtual Machine by following these instructions

    (If you are not well-versed command-line interfaces, we recommend the "VirtualBox" installation. Otherwise, we recommend the "Vagrant VM" installation.)

  2. In the OpenKIM VM, download the following presentations and training material that will be referred to and used by the online lectures.

    Unpack the training material tarball using the following Unix/Linux command:

    % tar zxvf openkim-boot-camp-12Aug2014.tgz
    

    This package contains the following example files (among others):

    openkim-boot-camp-12Aug2014/kim-api-examples/models/ex_model_Ar_P_Morse_01C/
    openkim-boot-camp-12Aug2014/kim-api-examples/models/ex_model_Ar_P_Morse_02C/
    ....
    openkim-boot-camp-12Aug2014/kim-api-examples/models/ex_model_Ar_P_Morse_14C/
    

    Each of these examples is incrementally more complex than the previous one. These examples provide a good way to develop an understanding of the KIM API.

    The online lectures go over these examples and the rest of the OpenKIM system.

  3. Watch the online lectures:
    • Overview of the KIM Project by Prof. Ellad B. Tadmor…. VIEW LECTURE

      • Motivation for the KIM project and its goals
      • Basic OpenKIM.org components (Data, Models, Tests)
      • Processing pipeline and the KIM API
      • Examples of how OpenKIM.org will work in practice
    • Introduction to the KIM API by Prof. Ryan S. Elliott – Part I…. VIEW LECTURE

      • Definition of basic concepts for the KIM API
      • Simulators and Models
      • Configurations
      • Particle Types (listed-contributing, listed-padding, image-padding)
      • Neighbor lists (Full and Half)
    • Introduction to the KIM API by Prof. Ryan S. Elliott – Part II…. VIEW LECTURE

      • KIM API Domain Decomposition scheme for parallel computing
      • KIM Descriptor files (".kim" files)
      • Example Tests in C++
    • KIM API (cont.) & Introduction to the OpenKIM Repository by Prof. Ellad B. Tadmor…. VIEW LECTURE

      • Example Models in C
      • Example Model in Fortran 2003
      • OpenKIM Repository
      • Property Definition Framework
    • Introduction to OpenKIM Tests by Daniel Karls…. VIEW LECTURE

      • Test Drivers and Tests
      • Example LAMMPS Test
      • OpenKIM Visualizers
  4. Do the "Boot Camp" exercises given in the boot-camp-exercises-12Aug2014.pdf file (included in the training material tarball; See step 2).

    Compare your results with the solutions…. boot-camp-12Aug2014-exercise-solutions.pdf

    The exercises involve simulations using a basic KIM-compliant molecular statics/molecular dynamics code called "MiniMol" (included in the training material tarball and available on the OpenKIM VM; See steps 1 & 2).

    All of the data files needed for the Boot Camp exercises are stored in the boot-camp-exercises/MiniMol_files directory.

  5. Read the "README" file in the docs directory of the KIM API distribution package:

    ~/kim-api/docs/README

    Here ~ represents the openkim home directory on the OpenKIM VM. The README file walks you through the examples provided with the KIM API distribution and directs you to other documentation files that you should read.

With the above training completed, a user should be ready to adapt existing code to become KIM-Compliant and to write new KIM-Compliant code from scratch.

To test your understanding of this process, you can try the following exercise. Take a simple stand-alone program that reads a file with atom types and coordinates and, treating this as an isolated cluster of atoms, computes the system's energy and the energy and force components for each atom. Your task is to transform this program into two parts: A KIM-Compliant Model (kcc_model_exp6) and a KIM-Compliant Simulator (kcc_test_cluster). The example codes (in C and Fortran 90) can be downloaded 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.)