Guide to KIM IDs

KIM IDs are permanent identifiers for content stored in the OpenKIM Repository. A KIM ID includes a code that identifies the item and a version number. Any changes to computer programs (Models, Tests, Verification Checks) that could result in different numerical values, or changes to the numerical values in Reference Data, lead to a version increment in the KIM ID. This makes it possible to reproduce results since the specific version of a specific item can be retrieved using its KIM ID. (Note that although KIM IDs are unique permanent identifiers, for citation purposes it is recommended to use DOIs issued by OpenKIM, see KIM DOIs and Citing KIM Items).

KIM IDs have the format:

CC_DDDDDDDDDDDDD_VVV

where

CC is a two-letter alphabetical code:

  • MO – Portable Model
  • MD – Model Driver
  • TE – Test
  • TD – Test Driver
  • RD – Reference Data
  • SM – Simulator Model
  • VC – Verification Check
  • VZ – Visualizer

DDDDDDDDDDDD is a 12-digit randomly assigned integer code.

VVV is a 3-digit version number starting at 000.


Extended KIM IDs

The Extended KIM ID Prefix is a human readable prefix (100 characters max) which is prepended to the Short KIM ID, separated by two consecutive underscores, to form the Extended KIM ID:

<Extended KIM ID Prefix>__CC_DDDDDDDDDDDDD_VVV

An Extended KIM ID Prefix can only contain alphanumeric characters (letters and digits) and underscores, and must begin with a letter. Unicode characters are not allowed.


Extended KIM IDs for Portable Models, Model Drivers and Simulator Models

The recommended format of the prefix for Portable Models, Model Drivers and Simulator Models are:

Portable Model<model type>_<model type info>_<developer name(s)>_<misc info>_<supported species>
Model Driver<model type>_<model type info>
Simulator ModelSim_<simulator name>_<model type>_<model type info>_<developer name(s)>_<misc info>_<supported species>
Portable Model

The recommended format for the prefix of a Portable Model is a series of elements in camel case separated by underscores:

<model type>_<model type info>_<developer name(s)>_<misc info>_<supported species>

<model type>
A brief description of the model type, e.g. "LJ", "EAM", etc.*
<model type info>
(Optional) additional information modifying the potential type, such as the code from which the driver originates (e.g. "Dynamo"), type of interpolation for tabulated potentials (e.g. "CubicNaturalSpline"), etc.*
<developer name(s)>
The names of the people who developed the model e.g. "StillingerWeber". By convention the list should be limited to at most three developers.
<misc info>
(Optional) additional information beyond the model type and developers that helps to identify the model, e.g. the year the model was developed and/or published in literature, a general term commonly used in describing this model (e.g. "Universal3" for a particular group of EAM models), or a combination of the year and a descriptor (e.g. "2003RDX" for a potential for RDX published in 2003).
<supported species>
The list of supported species (e.g. "NiAl"). Note that the species do not need to appear in alphabetical order if the ordering conveys some information as to the intent of the model. (It is recommended that the order of the species agrees with the ordering specified in the model's parameter file(s).) Alternatively, instead of species, it is permissible to use a term characterizing a group of species (e.g. "Universal" (for all species) or "TransitionMetals").

* Note that for a Portable Model that employs a Model Driver, the convention is to use the same <model type>_<model type info>_ prefix as for the corresponding Model Driver. For example, all models using the EAM_Dynamo driver begin with EAM_Dynamo_.

Examples:
  • EAM_CubicNaturalSpline_ErcolessiAdams_1994_Al__MO_800509458712_002
  • EAM_Dynamo_FoilesBaskesDaw_1986Universal3_Ag__MO_626948998302_000
  • LJ_ElliottAkerson_2015_Universal__MO_959249795837_003
  • SW_BalamaneHauchShi_2017Brittle_Si__MO_381114941873_002
Model Driver

The recommended format for the prefix of a KIM Model Driver is a series of elements in camel case separated by underscores:

<model type>_<model type info>

<model type>
A brief description of the model type, e.g. "LJ", "EAM", etc.*
<model type info>
(Optional) additional information modifying the potential type, such as the code from which the driver originates (e.g. "Dynamo"), type of interpolation for tabulated potentials (e.g. "CubicNaturalSpline"), etc.*

* Note that for a Portable Model that employs a Model Driver, the convention is to use the same <model type>_<model type info>_ prefix as for the corresponding Model Driver. For example, all models using the EAM_Dynamo driver begin with EAM_Dynamo_.

Examples:
  • EAM_CubicNaturalSpline__MD_853402641673_002
  • EAM_Dynamo__MD_120291908751_005
  • LJ__MD_414112407348_003
  • SW__MD_335816936951_004
Simulator Model

The recommended format for the prefix of a KIM Simulator Model (SM) begins with Sim_ and is followed by a series of elements in camel case separated by underscores:

Sim_<simulator name>_<model type>_<model type info>_<developer name(s)>_<misc info>_<supported species>

<simulator name>
The name of the simulation code with which this SM is compatible, e.g. "ASAP", "DLPOLY", "GULP", "LAMMPS", etc.
<model type>
The term used by the simulator to describe the potential type, e.g. for LAMMPS this would be the pair style ("ADP", "AIREBO", ...)
<model type info>
(Optional) additional information identifying the specific type of potential, e.g. "Morse" to distinguish a particular variant of the LAMMPS AIREBO pair style.
<developer name(s)>
The names of the people who developed the model e.g. "StillingerWeber". By convention the list should be limited to at most three developers.
<misc info>
(Optional) additional information beyond the model type and developers that helps to identify the model, e.g. the year the model was developed and/or published in literature, a general term commonly used in describing this model (e.g. "Universal3" for a particular group of EAM models), or a combination of the year and a descriptor (e.g. "2003RDX" for a potential for RDX published in 2003).
<supported species>
The list of supported species (e.g. "NiAl"). Note that the species do not need to appear in alphabetical order if the ordering conveys some information as to the intent of the model. (It is recommended that the order of the species agrees with the ordering specified in the model's parameter file(s).) Alternatively, instead of species, it is permissible to use a term characterizing a group of species (e.g. "Universal" (for all species) or "TransitionMetals").
Examples:
  • Sim_LAMMPS_ADP_ApostolMishin_2011_AlCu__SM_667696763561_000
  • Sim_LAMMPS_AIREBO_LJ_StuartTuteinHarrison_2000_CH__SM_069621990420_000
  • Sim_LAMMPS_EIM_Zhou_2010_BrClCsFIKLiNaRb__SM_259779394709_000


Extended KIM IDs for Tests and Test Drivers

The recommended format of the prefix for Tests and Test Drivers are:

Test Driver<test type/name>
Test<test type/name>_<test info>_<supported element(s)>

<test type/name>
A short description of the test, e.g. "ElasticConstantsCubic" indicates that this test computes the elastic constants of a cubic crystal.

<test info>
This includes additional information distinguishing the test if needed, e.g. "fcc" indicates that the "ElasticConstantsCubic" test is for an fcc crystal.

<supported element(s)>
The list of supported elements in camel case (e.g. "AlNi").

By convention, Tests associated with a Test Driver begin with their associated Test Driver prefix.

Examples:
  • ElasticConstantsCubic__TD_011862047401_005
  • ElasticConstantsCubic_fcc_Al__TE_944469580177_005


KIM IDs Reserved for Development

The OpenKIM system is responsible for assigning the unique 12-digit integer code that makes up the middle part of an item's KIM ID. However, the KIM Processing Pipeline and KIM Docker Container provided for user development expect items to have KIM IDs conforming to the format described above. Thus, if you would like to develop new Portable Models, Model Drivers, Tests, and/or Test Drivers, your development code will need to conform to this format.

A special set of 12-digit numbers has been reserved for development use only:

000000DDDDDD

For example, a development Model Driver and associated Portable Model might have the following extended KIM IDs:

  • NewPotential__MD_000000000001_000
  • NewPotential_MeMyselfI_2020_CHONP__MO_000000000001_000

Developers may take advantage of the 3-digit version numbering to label different versions of their development codes:

  • NewPotential__MD_000000000001_000
  • NewPotential__MD_000000000001_001
  • NewPotential__MD_000000000001_002

All new items submitted to the OpenKIM system must conform to this development numbering range.




← EDN Format
KIM Item Funding References →