Obtaining KIM Models

In order to use KIM Portable Models (PMs), which may depend on Model Drivers (MDs), or Simulator Models (SMs) on your system, you must install the KIM application programming interface (API) along with the specific models that you are interested in using. There are several options for doing so. The recommended methods for installing the API are through conda-forge or by installing from source. Once the API is installed, you can use the included kim-api-collections-management utility to automatically download, build, and install any models you wish to use (see Installing Models). Linux and macOS are supported. Users of Windows 10 and newer can use the same procedure as Linux using the Windows Substystem for Linux.

• conda-forge
• Installing from source
• Installing models
• Other package managers (deprecated)
  • macOS
    • Homebrew macOS
  • Linux
    • Ubuntu Linux
    • openSUSE Linux
    • Fedora Linux
    • FreeBSD Ports
    • Arch User Repository (AUR)
  • Spack

Conda

Conda is the recommended way to obtain pre-built KIM API binaries. Linux and macOS packages are available on conda-forge for several CPU architectures (see the Platforms badge above). To learn more about Conda, see the documentation. You can initialize a new Conda environment (in this example named kim-env) from the kim-api package on conda-forge:

$ conda create -n kim-env -c conda-forge kim-api=2.3.0

Alternatively, you can install the kim-api package in an existing Conda environment with the following command:

$ conda install -c conda-forge kim-api=2.3.0

Once kim-api is installed, you can use the included kim-api-collections-management utility to install models. It is important to specify the version number 2.3.0 in the commands above for this to work, as older versions of the Conda package do not support building models.

If you need to use kimpy, which is the package containing Python bindings to the KIM API, you should only install the kimpy conda-forge package as it depends on the kim-api package, so kim-api will be installed automatically if you install kimpy. This is required to use KIM models with the Atomic Simulation Environment (ASE), which needs to be installed separately (usually as the conda-forge ase package). The lammps conda-forge package also depends on kim-api, so there is no need to install the kim-api package separately. There is also an openkim-models package available from conda-forge. It contains all available OpenKIM models at the time of its release, but is no longer updated and does not contain the latest models and model drivers. It also automatically installs kim-api and may be supplemented by installing additional models individually.

NOTE: The kimpy,lammps, and openkim-models packages on conda-forge do not specify a version of their kim-api dependency, and Conda may install an older version of kim-api to resolve conflicts. Conda may also downgrade kim-api if you install other packages in the same environment. Older versions of the kim-api package do not support building models. Because of this, if you are having issues installing models, then the first troubleshooting step is to re-run

$ conda install -c conda-forge kim-api=2.3.0

to ensure that you have version 2.3.0 of the kim-api package, then try installing models again.

Thanks to Jan Janssen (Max-Planck-Institut für Eisenforschung) for helping to make conda-forge packages available.

Installing the KIM API from Source

The KIM API currently supports Unix/Linux and macOS systems. Installation from source involves downloading the kim-api package, unpacking it, and following instructions to compile and install the code. This will require you to have the necessary compilers and build tools available on your system. Typically, this includes the GNU C, C++, and Fortran compilers (gcc, g++, and gfortran), as well as CMake version 3.4 or newer (cmake), make, xxd (which is part of the vim or vim-common package depending on the system), wget, tar, and various standard utilities from the coreutils package.

To install the KIM API do the following:

1. Download the latest version of the API:
   Download kim-api-2.3.0.txz (OpenGPG Signature) — released 2022/03/17

2. If desired, verify the signature of the source code archive.

   • Release tarballs are signed with Ryan S. Elliott's <relliott@umn.edu> public key
     (https://z.umn.edu/relliott_asc [576D4997C4D51D92]).

     To verify the release tarball, first download the public key and import it:

     $ gpg --import relliott.asc
     

     After downloading the tarball and signature, run:

     $ gpg --verify kim-api-2.3.0.txz.asc kim-api-2.3.0.txz
     

3. Unpack the archive.

   • On Unix/Linux and macOS systems, type:

     $ tar Jxvf kim-api-2.3.0.txz
     

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

4. Read the README.md file in the new directory.

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

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

   • Quick start: try the following

      $ cd kim-api-2.3.0
      $ 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.

The KIM API supports four "collections" of PMs, MDs, and SMs. These are the "system-collection", the "user-collection", the "environment-variable-collection", and the "CWD-collection". This provides the user with a great deal of flexibility on where models 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 Items. Dependencies on MDs are automatically handled. For example, to install the Stillinger-Weber potential for silicon in the user collection do:

$ kim-api-collections-management install user SW_StillingerWeber_1985_Si__MO_405512056662_005

Note that this model requires a MD (SW__MD_335816936951_004), which will be automatically downloaded and installed.

To see the list of the PMs, MDs, and SMs installed in all collections do:

$ kim-api-collections-management list

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

NOTE: If you are having issues installing models in a Conda environment, see the note in the Conda installation section for the first troubleshooting step.

Installation Using Other Package Managers (Deprecated)

Packages for the KIM API and OpenKIM models are available for many other package managers, including Homebrew macOS, native package managers for various Unix/Linux distributions, and Spack. These methods are no longer actively supported, and may be outdated. Because the API is stable, many of these methods will remain operational for a long time. In addition to the kim-api package, the openkim-models package is available in many cases. The openkim-models package contains all models in the OpenKIM repository at the time of its release, but is no longer updated and does not contain the latest models and model drivers. The table to the right lists the package managers or operating systems for which packages are available. For each system, the currently available versions of the openkim-models and kim-api packages are listed. Green indicates the most current version available, whereas red indicates an older version. (The openkim-models snapshot source code archives are available here).

In most cases, openkim-models will automatically install the kim-api package, but some exceptions are described in the sections below for individual package managers. Once the kim-api package is installed, you can automatically install additional models from source as long as you have all the prerequisites (typically just compilers, but sometimes others such as LAPACK, BLAS, Torch, etc.). The openkim-models package installs items in the system collection. If you choose to install it and supplement it with newer models installed from source, it is suggested that the latter be installed to the user collection to avoid any possible clashes between the package manager and the items installed from source.

Below are examples and instructions for installing openkim-models using some of the supported package managers.

Homebrew macOS

$ brew install openkim-models

Thanks to Ryan Elliott (UMN) for helping to make macOS Homebrew binaries available.

Ubuntu Linux PPA

On Ubuntu, the most recent binaries are available from the openkim/latest Personal Package Archive (PPA). The commands necessary to setup the PPA on your system are:

$ sudo add-apt-repository ppa:openkim/latest
$ sudo apt-get update

On Ubuntu, in order to have access to the kim-api-collections-management (and other utilities), you must explicitly install the libkim-api-dev package.

$ sudo apt-get install libkim-api-dev openkim-models

Ubuntu Linux Release

On Ubuntu releases, such as 23.10 (Mantic Minotaur), binaries are also available (although they may be older than those available from the PPA). To have access to the kim-api-collections-management (and other utilities), you must explicitly install the libkim-api-dev package.

$ sudo apt-get install libkim-api-dev openkim-models

Thanks to Anton Gladky (gladky.anton at gmail.com) for helping to make Ubuntu binaries available.

openSUSE Linux

On openSUSE, in order to have access to the kim-api-collections-management (and other utilities), you must also explicitly install the kim-api package.

$ sudo zypper install kim-api openkim-models

Thanks to Christoph Junghans (LANL) for helping make openSUSE binaries available.

Fedora Linux

$ sudo dnf install openkim-models

Thanks to Christoph Junghans (LANL) for helping make Fedora binaries available.

FreeBSD Ports

$ sudo pkg install openkim-models

Thanks to yuri@freebsd.org for helping make FreeBSD ports available.

Arch User Repository (AUR)

There are two scripts available in the unofficial Arch User Repository (AUR). One for the kim-api package and one for the openkim-models package. Note, the AUR provides build-scripts (not precompiled binaries) that download the source and then build the package(s) on your machine.

To install, you will need to have the base-devel, git, and pyalpm packages installed.

$ git clone -q https://aur.archlinux.org/kim-api.git
$ cd kim-api
$ makepkg -fsrim --noconfirm
$ cd ..
$ git clone -q https://aur.archlinux.org/openkim-models.git
$ cd openkim-models
$ makepkg -fsrim --noconfirm

Thanks for Daniel Schopf <schopf.dan at gmail dot com> for helping make the ARU ports available.

Spack (https://spack.io)

Spack is a package manager for supercomputers, Linux, and macOS that automatically builds packages from source. The below commands will get you started, but see the docs for more. The openkim-models package is not supported on the latest versions of Spack, only kim-api.

$ git clone https://github.com/spack/spack.git
$ source spack/share/spack/setup-env.sh
$ spack install kim-api
$ spack load kim-api

You can now proceed to install any models you wish to use from source. Thanks to Christoph Junghans (LANL) and Ryan Elliott (UMN) for helping make Spack support available.