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)[source]¶
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:
- 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