KIM

Note

This package requires the KIM API package, which is hosted on GitHub and available through many binary package managers. See openkim.org/kim-api for installation options.

Note

This package requires the kimpy python package, which is hosted on GitHub and also made available through PyPI.

Overview

This package contains a calculator interface that allows one to easily use any potential archived in Open Knowledgebase of Interatomic Models (OpenKIM) through ASE. OpenKIM is an NSF-funded project aimed at providing easy access to standardized implementations of classical interatomic potentials that can be used with a variety of molecular simulation codes.

If you haven’t done so already, you’ll need to install the KIM Application Programming Interface (API) and the kimpy python package in order to use this calculator. The simplest way to install the former is to use your operating system’s native package manager to install the ‘openkim-models’ package, which will install both the KIM API and a snapshot of binaries of all of the current models housed in the OpenKIM repository (see https://openkim.org/doc/usage/obtaining-models for instructions). Otherwise, the ‘kim-api’ package can be installed by itself, which will not include any models beyond the examples bundled with the KIM API. The kimpy package can be installed from PyPI using pip: pip install --user kimpy.

As an example, suppose we want to know the potential energy predicted by the example model “ex_model_Ar_P_Morse_07C” for an FCC argon lattice at a lattice spacing of 5.25 Angstroms. This can be accomplished in a manner similar to how most other ASE calculators are used, where the name of the KIM model is passed as an argument:

from ase.lattice.cubic import FaceCenteredCubic
from ase.calculators.kim.kim import KIM

atoms = FaceCenteredCubic(symbol='Ar', latticeconstant=5.25, size=(1,1,1))
calc = KIM("ex_model_Ar_P_Morse_07C")
atoms.calc = calc

energy = atoms.get_potential_energy()
print("Potential energy: {} eV".format(energy))

To use any other KIM model you have installed, simply substitute its name as the argument to KIM. You can browse the models available in OpenKIM for a specific element by visiting https://openkim.org and clicking on it in the periodic table. Each model is identified by its extended KIM ID, which consists of a human-readable string followed by a numeric code assigned to it. Clicking on an individual model will display a page containing additional information about it, including its predictions for various material properties. Information on how to install KIM Models can be found at https://openkim.org/doc/usage/obtaining-models/.

See below for a more detailed explanation of this package and additional options.

Implementation

In order to explain the structure of this package, we must first describe the two different types of interatomic potentials in KIM: [1]

• Portable Models (PMs) A KIM Portable Model (PM) is an interatomic potential designed to work with any simulator that supports the KIM API portable model interface.

• Simulator Models (SMs) A KIM Simulator Model (SM) is an interatomic potential designed to work with a single simulator.

These two types of KIM models require different calculators to work: PMs work through a designated calculator that uses the kimpy library (which provides a set of python bindings to the KIM API) in order to set up communication between ASE and the model. This allows, for example, the positions of the atoms and the neighbor list in ASE to be communicated to the model, and for the energy and forces predicted by the model for that configuration to be communicated back to ASE in a standard format. On the other hand, SMs are a set of simulator commands, usually accompanied by one or more parameter files, [2] that are passed to a calculator corresponding to the specific simulator associated with the SM.

Because of this separation, the ase.calculators.kim package consists of two modules: ase.calculators.kim.kim and ase.calculators.kim.kimmodel. The first of these contains a wrapper function named ase.calculators.kim.kim.KIM() that takes as input the name of a KIM model installed on your machine, automatically determines whether it is a PM or an SM, then constructs and returns an appropriate ASE calculator. [3] For example, if the name of an installed PM is passed, the KIM function will (by default) initialize an instance of ase.calculators.kim.kimmodel.KIMModelCalculator for it and return it as its output. If the name of a LAMMPS-based SM is passed, the calculator will (by default) return an instance of the ase.calculators.lammpslib.LAMMPSlib calculator. The specific calculator type returned can be controlled using the simulator argument.

ase.calculators.kim.kim.KIM(model_name, simulator=None, options=None, debug=False)

Calculator wrapper for OpenKIM models

Returns a suitable calculator that can be used with any model archived in the Open Knowledgebase of Interatomic Models (OpenKIM) at https://openkim.org. There are two kinds of models in KIM: Portable Models (PMs), which can be used with any KIM API-compliant simulator, and Simulator Models (SMs), which are essentially just wrappers around native commands in a specific simulator (often combined with values for the model parameters). PMs published on openkim.org contain the string ‘__MO_’ in their name, while SMs published on openkim.org contain the string ‘__SM_’ in their name.

Parameters:

• model_name (str) – The name of the KIM model installed on your system. KIM models published on openkim.org follow a specific naming scheme (see https://openkim.org/doc/schema/kim-ids).

• simulator (str, optional) –

  Used to identify the ASE calculator that will be used. Currently supported values include ‘kimmodel’, ‘lammpslib’, ‘lammpsrun’ and ‘asap’, and correspond to different calculators as follows:

  • kimmodel (default for PMs) : ase.calculators.kim.kimmodel.KIMModelCalculator

  • lammpsrun (PMs or LAMMPS SMs) : ase.calculators.lammpsrun.LAMMPS

  • lammpslib (default for LAMMPS SMs) : ase.calculators.lammpslib.LAMMPSlib

  • asap (PMs) : asap3.Internal.OpenKIMcalculator.OpenKIMcalculator

  • asap (ASAP SMs) : asap3.Internal.BuiltinPotentials.EMT

  In general, this argument should be omitted, in which case a calculator compatible with the specified model will automatically be determined.

• options (dict, optional) –

  Additional options passed to the initializer of the selected calculator. If simulator == ‘kimmodel’, possible options are:

  • ase_neigh (bool) : Whether to use the kimpy neighbor list library (False) or use ASE’s internal neighbor list mechanism (True). Usually kimpy’s neighbor list library will be faster. (Default: False)

  • neigh_skin_ratio (float) : The skin distance used for neighbor list construction, expressed as a fraction of the model cutoff (Default: 0.2)

  • release_GIL (bool) : Whether to release python GIL. Releasing the GIL allows a KIM model to run with multiple concurrent threads. (Default: False)

  See the ASE LAMMPS calculators doc page (https://wiki.fysik.dtu.dk/ase/ase/calculators/lammps.html) for available options for the lammpslib and lammpsrun calculators.

• debug (bool, optional) – If True, detailed information is printed to stdout. If the lammpsrun calculator is being used, this also serves as the value of the keep_tmp_files option. (Default: False)

Returns:

An ASE-compatible calculator. Currently, this will be an instance of KIMModelCalculator, LAMMPS (the lammpsrun calculator), or LAMMPSlib, which are all defined in the ASE codebase, or an instance of either OpenKIMcalculator or EMT defined in the asap3 codebase.

Return type:

ase.calculators.calculator.Calculator

Raises:

KIMCalculatorError – Indicates an error occurred in initializing the calculator, e.g. due to incompatible combinations of argument values

Advanced Usage

Recalling the example given in the Overview section at the top of this page, no arguments are passed to the KIM function other than the name of a portable model, ex_model_Ar_P_Morse_07C. From the Implementation section, this means that the calc object returned is actually an instance of ase.calculators.kim.kimmodel.KIMModelCalculator and uses the neighbor list library implemented in kimpy. If we wanted to use ASE’s internal neighbor list mechanism, we could specify it by modifying the corresponding line to:

calc = KIM("ex_model_Ar_P_Morse_07C", options={"ase_neigh": True})

If, for some reason, we want to run our portable model with the ASE LAMMPS calculator (ase.calculators.lammpsrun.LAMMPS), we can specify it using the simulator argument:

calc = KIM("ex_model_Ar_P_Morse_07C", simulator="lammpsrun")

Using a KIM simulator model requires no additional effort. Using the example LAMMPS-based simulator model bundled with the KIM API, “Sim_LAMMPS_LJcut_AkersonElliott_Alchemy_PbAu”:

from ase.lattice.cubic import FaceCenteredCubic
from ase.calculators.kim.kim import KIM

atoms = FaceCenteredCubic(symbol='Au', latticeconstant=4.07, size=(1,1,1))
calc = KIM("Sim_LAMMPS_LJcut_AkersonElliott_Alchemy_PbAu")
atoms.calc = calc

energy = atoms.get_potential_energy()
print("Potential energy: {} eV".format(energy))

In this case, because simulator was not specified, the default behavior is that the object calc returned is an instance of ase.calculators.lammpslib.LAMMPSlib.

Finally, if one instantiates the calculator for a KIM Portable Model that registers its parameters, they can be accessed or mutated using the get_parameters and set_parameters methods. For example, to print the components of the parameters epsilons and sigmas in the Lennard-Jones universal model corresponding to Mo-Mo (index 4879), Mo-S (index 2006) and S-S (index 1980) interactions, one can do the following:

model = "LJ_ElliottAkerson_2015_Universal__MO_959249795837_003"
calc = KIM(model)
print(calc.get_parameters(epsilons=[4879, 2006, 1980],
                          sigmas=[4879, 2006, 1980])

This will print a dictionary whose keys are the parameter names and whose values are lists that each contain two sublists. The first contains the set of indices in the parameters arrays that were requested and the second contains the corresponding parameter values:

{'epsilons': [[4879, 2006, 1980],
              [4.47499, 4.421814057295943, 4.36927]],
 'sigmas': [[4879, 2006, 1980],
            [2.74397, 2.30743, 1.87089]]}

Or, suppose we want to set the values of the components of the epsilons parameter of the same model corresponding to Mo-Mo, Mo-S, and S-S to 5.0, 4.5, and 4.0, respectively. In this case, a syntax similar is used:

model = "LJ_ElliottAkerson_2015_Universal__MO_959249795837_003"
calc = KIM(model)
calc.set_parameters(epsilons=[[4879, 2006, 1980],
                              [5.0, 4.5, 4.0]])

Note

For models with parameter arrays that contain many components, such as the Lennard-Jones universal model above, one must refer to the documentation of the model itself (or its model driver, if it uses one) in order to ascertain the meaning of the different components of the parameter arrays.

Footnotes

[1]

See here for more details about different types of content in KIM.

[2]

Simulator Models (SMs) are actually always used in the form of a binary shared object. This shared object contains not only the commands and other metadata related to the SM within it, but also has any relevant parameter files (if any) directly compiled into it.

[3]

As a convenience, this module also contains the function ase.calculators.kim.kim.get_model_supported_species(), which retrieves a tuple of all of the species that a model can compute interactions for.