Getting Started with KIM

Welcome to the Open Knowledgebase of Interatomic Models (OpenKIM) website!

OpenKIM is a major open source effort funded by the NSF to develop standards and improve the reliability of molecular simulations.

The OpenKIM Repository contains interatomic models (potentials and force fields), verification checks that inspect models for coding correctness, simulation codes (called "tests") that compute different material properties, and first-principles/experimental reference data. Whenever a new model is added to the system it is automatically coupled and run with all compatible verification checks and tests. Similarly any new verification check or test is automatically coupled with all compatible models. The verification check and test results obtained in this fashion are inserted into the OpenKIM Repository and can be explored using the OpenKIM interface including visualizations comparing the predictions of different models with each other and with reference data. This allows users to select and download appropriate models for their application. Models archived in OpenKIM can be used seamlessly with several major simulation code that are compatible with the KIM framework.

This document briefly describes the main OpenKIM features and capabilities and points to more information on how to use them. This is a good place to start if you are new to KIM (or need a reminder on how to do something).

Curated Storage of KIM Content

The OpenKIM Repository provides permanent curated storage of interatomic models, verification checks, material property tests, reference data, and model predictions (test results). (For details, see the types of KIM content.) Best practice revision and provenance control are employed to ensure content integrity.

  • All content archived in OpenKIM is reviewed by the KIM Editor for quality and is subject to full provenance control. Each item is associated with a maintainer responsible for the integrity of the content. All changes are tracked and recorded.

  • Each item in OpenKIM is identified by a unique, permanent KIM ID of the following form: CC_DDDDDDDDDDDDD_VVV, where CC denotes the item type, DDDDDDDDDDDDD is a 12-digit code, and VVV is a version number. Any changes that can result in different numerical values lead to a version increment in the KIM ID. This makes it possible to reproduce simulations since the specific version of a specific interatomic model used can be retrieved using its KIM ID. (For details, see the Guide to KIM IDs.)

  • Each item in OpenKIM is associated with an Item Page (Model Page, Test Page, etc.), which provides information on the item, simulation results, associated files, and a Wiki with documentation and comments by contributors and users of the item. The URL for the item page has the following form: https://openkim.org/id/KIM_ID, where KIM_ID is replaced by the item's KIM ID. See for example, the Model Page for the Stillinger-Weber potential.

  • OpenKIM is a member organization of DataCite and issues digital object identifiers (DOIs) to certain items archived in the OpenKIM Repository including Models, Model Drivers (software used by Models), Test Drivers (software used by Tests), and Verification Checks. This makes it possible to cite OpenKIM content in publications (such as a KIM Model used in a simulation) to give credit to the developers and further facilitate reproducibility. For more details, see KIM DOIs and Citing KIM Items.

  • The OpenKIM Repository is designed to be user-extendable. Contributions of new Models, Tests, Verification Checks, Reference Data, and Visualizers are encouraged. See instructions on adding new content to KIM.

Testing and Verifying Models

Interatomic models stored in the OpenKIM Repository are exhaustively tested providing users with a wealth of information to help them select a suitable model for a given application.

  • Each Model is subjected to a series of Verification Checks evaluating its integrity, e.g. Are the forces returned by the model consistent with those obtained through numerical differentiation of the energy? Does the model have continuous energy and derivatives at its cutoff? and so on. The Model is graded on each Verification Check and the results are presented in a dashboard on its Model Page. To learn more, see About Verification Checks.

  • The OpenKIM Repository contains KIM Tests, uploaded by researchers, that compute material properties of interest (such as equilibrium crystal structures, elastic constants, surface energies, thermal properties, etc.). The Tests are applied to all compatible interatomic models in the repository. The results are stored and can be examined and compared using visualization tools and text-based tools. Timing information is also provided so that the relative expense of different Models for the same computation can be assessed.

  • OpenKIM provides a framework for researchers to broadly distribute and accelerate their molecular simulations research. It is the aim of the KIM project for high-quality KIM Tests to become standard, citeable methods for computing important material properties. A great deal of expertise is required to compute material properties rigorously and robustly. For more information on KIM Tests and to learn how you can work with the KIM Team on adapting your simulations and expertise to craft a new test, see the Introduction to KIM Tests.

  • Test results archived in the OpenKIM Repository are accessible through the OpenKIM Query API, which is interfaced into some simulation codes. This means that the predictions of a specific model (e.g. the equilibrium lattice constant of a diamond crystal, or the elastic constant of an L12 alloy) can be used as part of the setup and analysis of molecular simulations. As an example of how this works, see KIM queries in LAMMPS. Query statistics are collected so that Test contributors have documented evidence for the impact of their work.

Using KIM Models

Models archived in OpenKIM can be used with simulation codes that are compatible with the KIM Application Programming Interface (API). There are two types of OpenKIM models: Portable Models (PMs) that can be used in multiple simulation codes, and Simulator Models (SMs) that only work with a specific simulator.

  • A KIM Portable Model is an independent computer implementation of an interatomic model written in one of the languages supported by KIM (C, C++, Fortran) that conforms to the KIM API Portable Model Interface (PMI) standard. A KIM PM will work seamlessly with any simulation code that supports the KIM API/PMI standard (much like a DVD works seamlessly with a DVD player). (See current list of KIM-compliant codes here).

  • A KIM Simulator Model is a package curated on OpenKIM that specifies how to setup and run a model that is implemented as an integrated part of a simulation code (simulator). For simulators that support the KIM API Simulator Model Interface (SMI), KIM SM's can be obtained and used in a simple fashion. A KIM SM package includes all of the necessary parameter files, simulator input commands, and metadata (supported species, units, etc.) needed to run the model in its native simulator. Currently only LAMMPS supports the KIM API/SMI; OpenKIM has a large number of LAMMPS SMs. Uploading a new SM to OpenKIM is as simple as filling in an online form.

  • The fact that a Portable Model includes the complete computer implementation of the interatomic model (and not just parameter files used by another code as for a Simulator Model) is important, since in some cases the same parameter file can lead to different results when read in by different programs. (For a discussion of this effect for tabulated EAM potentials, see Wen et al. (2015).)

  • Both KIM PMs and SMs provide support for managing the units requirements of the simulator and interatomic model. PMs can be designed to convert the model's parameters to conform to the units requested by the calling simulator. For SMs, a mechanism can be added to the simulator to manage unit conversion. For an example, see unit conversion handling for KIM SMs in LAMMPS. This simplifies the use of interatomic models and reduces the likelihood of errors due to incompatible units.

  • To use KIM Models with a KIM-compliant simulation code, you first need to install the KIM API. Installation from source and from binary are possible. See detailed instructions on how to install the KIM API and how to download and install KIM Models. Once this done, using a KIM Model simply involves providing its KIM ID in the simulator input file. (See the instructions on how to use KIM Models in your simulator.)

  • OpenKIM provides a framework for interatomic model developers to distribute their interatomic models in a reliable fashion providing their users with information on usage and citation of the model on its Model Page (see above), which they can maintain themselves. In addition, as noted above, models conforming to the KIM API/PMI (i.e. Portable Models) become available at once to a large number of simulation codes.

Becoming a KIM Member and Staying Informed

If you are still not a member, we encourage you to sign up. Becoming a KIM member is free and allows you to vote on important issues related to the project and its administration (see benefits of membership. KIM Members have the option of being informed of major developments via email. (For continuous updates on developments, follow OpenKIM on Twitter.) Note that you do not need to be a member to access KIM content.

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.