kimspec.edn Reference

The kimspec.edn file can be found in all KIM Items. It contains the minimal necessary metadata to describe a KIM Item for automated information exchange.

Guide to keys

KIM Item
Key in file Model Simulator Model Test Model Driver Test Driver Reference Data Test Result Error Verification Check Verification Result
atom-type-labels N/A N/A N/A N/A N/A N/A N/A N/A N/A
content-origin N/A N/A N/A
content-other-locations N/A N/A N/A
contributor-id N/A N/A N/A
data-method N/A N/A N/A N/A N/A N/A N/A N/A N/A
description N/A N/A N/A
developer N/A N/A N/A N/A
disclaimer N/A N/A N/A N/A
doi N/A N/A N/A
domain
error-result-id N/A N/A N/A N/A N/A N/A N/A N/A N/A
executables N/A
extended-id N/A N/A N/A N/A
funding N/A N/A N/A
implementer N/A N/A N/A
kim-api-version N/A N/A N/A N/A
maintainer-id N/A N/A N/A
matching-models N/A N/A N/A N/A N/A N/A N/A N/A
model N/A N/A N/A N/A N/A N/A N/A
model-driver N/A N/A N/A N/A N/A N/A N/A N/A N/A
potential-type N/A N/A N/A N/A N/A N/A N/A N/A
properties N/A N/A N/A N/A N/A N/A
publication-year N/A N/A N/A
run-compatibility N/A N/A N/A N/A N/A N/A N/A N/A N/A
short-id N/A N/A N/A N/A N/A N/A N/A N/A N/A
simulator-model N/A N/A N/A N/A N/A N/A N/A
simulator-name N/A N/A N/A N/A N/A N/A
simulator-potential N/A N/A N/A N/A N/A N/A N/A N/A N/A
simulator-potential-compatibility N/A N/A N/A N/A N/A N/A N/A N/A N/A
source-citations N/A N/A N/A
species N/A N/A N/A N/A N/A
test N/A N/A N/A N/A N/A N/A N/A N/A
test-driver N/A N/A N/A N/A N/A N/A N/A N/A N/A
test-result-id N/A N/A N/A N/A N/A N/A N/A N/A N/A
title N/A N/A N/A N/A
verification-check N/A N/A N/A N/A N/A N/A N/A N/A
verification-result-id N/A N/A N/A N/A N/A N/A N/A N/A N/A

Required
Conditionally required
Optional
Optional on submission — May be provided, default will by added if not found
N/A Not Available



A description of common keys found in the kimspec.edn file follows.

atom-type-labels

If a special-purpose Simulator Model uses particle types distinct from their chemical species, it must provide this dictionary mapping each supported particle type to a chemical species. Non-atom particle types (e.g. virtual electrons) should be mapped to the value IGNORE.

Conditionally Required for: Simulator Model

content-origin

A description and/or web address to the online source where the material was obtained. Possible examples include 'Original content', 'Obtained from developer', 'Included in LAMMPS', a link to the relevant NIST IPR page, or the URL/ID/Access Date of a Materials Project entry.

Optional for: Model, Simulator Model, Test, Model Driver, Test Driver, Reference Data, Verification Check

content-other-locations

A description of and/or web address(es) to other location(s) where the content is available.

Optional for: Model, Simulator Model, Test, Model Driver, Test Driver, Reference Data, Verification Check

contributor-id

The unique OpenKIM User ID of the account that was used to submit the item. This should generally be omitted, as if the supplied contributor-id does not match that of the submitting account, it will be overwritten.

Optional on submission, will be added to all kimspec.edn files

data-method

The method used to generate an instance of Reference Data.

Must be one of: experiment, computation, or unknown

Required for: Reference Data

description

A short description describing its key features including for example: type of model (pair potential, 3-body potential, EAM, etc.), modeled elements (Ac, Ag, …, Zr), intended purpose, origin, and so on.

Required for: Model, Simulator Model, Test, Model Driver, Test Driver, Reference Data, Verification Check

developer

An array of strings, each of which is a KIM user uuid corresponding to a "developer" of the item. A developer of an item is someone who participated in creating the core intellectual content of the digital object, e.g. the functional form of an interatomic model or a specific parameter set for it.

Note:

  • Before an item is approved, the KIM Editor will consult with the uploader to determine the contents of this key. Uploaders do not need to directly specify the developers of an item in the upload forms.
  • Even a single entry must be enclosed in array brackets [].
  • See KIM Item Attribution for a more detailed description of what constitutes a developer.

Required for: Model, Simulator Model, Test, Model Driver, Test Driver, Reference Data, Verification Check

disclaimer

A short statement of applicability which will accompany any results computed using it. A developer can use the disclaimer to inform users of the intended use of this KIM Item.

Optional for: Model, Simulator Model, Test, Model Driver, Test Driver, Verification Check

doi

The digital object identifier associated with the KIM Item.

Optional on submission for Model, Simulator Model, Model Driver, Test Driver, Verification Check Optional for: Test, Reference Data

domain

The domain "openkim.org" is added to all KIM Items assigned IDs from the numbering authority at https://openkim.org/

Optional on submission, will be added to all kimspec.edn files

error-result-id

Unique identifier associated with an Error that contains the Short KIM ID of a Test or Verification Check and a Model, as well as a timestamp.

Example: TE_132463034437_000-and-MO_769582363439_004-1525996161-er

Required for: Error

executables

An array of strings containing the relative path and filename of all files marked with executable permissions.

Optional on submission, will be added to all kimspec.edn files

extended-id

The Extended KIM ID. This is the Short KIM ID with a descriptive prefix and two underscores. See the Guide to KIM IDs for more information.

Example: EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005

Required for: Model, Simulator Model, Test, Model Driver, Test Driver, Verification Check

funding

An array of dictionaries of funding sources acknowledged for supporting the development of the model.

For an item in the 'funding' array, the keys a user are allowed to define are:

  • Funder Name (Required)
    Description: 'Name of the funding provider.'
    Key: 'funder-name'
  • Award Number (Optional)
    Description: 'The code assigned by the funder to a sponsored award (grant).'
    Key: 'award-number'
  • Award URI (Optional)
    Description: 'The URI leading to a page provided by the funder for more information about the award (grant).'
    Key: 'award-uri'
  • Award Title (Optional)
    Description: 'The human readable title or name of the award (grant).'
    Key: 'award-title'

The Funder Name field is pre-populated with options provided by the Crossref Funder Registry.

The user may choose to enter their own selection, or choose an entry from the Crossref Funder Registry.

If they choose from the Registry, these additional fields are added to the 'funding' entry:

  • 'funder-identifier-type'. This is always "Crossref Funder ID".
  • 'funder-identifier'. This is the DOI link as defined by the Registry.
  • 'scheme-uri'. This is always "http://doi.org/". This defines the schema used by 'funder-identifier', and they are always a DOI link.
implementer

An array of strings, each of which is a KIM user uuid corresponding to an "implementer" of the item. An implementer of a digital object is someone responsible for its source code implementation or the format in which it is stored in OpenKIM.

Note:

  • Before an item is approved, the KIM Editor will consult with the uploader to determine the contents of this key. Uploaders do not need to directly specify the implementers of an item in the upload forms.
  • Even a single entry must be enclosed in array brackets [].
  • See KIM Item Attribution for a more detailed description of what constitutes an implementer.
kim-api-version

Version of the KIM API that this KIM Item is compatible with.

Required for: Model, Simulator Model, Test, Model Driver, Test Driver, Verification Check

maintainer-id

The unique OpenKIM User ID of the account that is responsible for a given KIM Item (and is allowed to create a new version of the item). This should generally be omitted, in which case it will be set equal to the contributor-id upon submission.

Optional on submission, will be added to all kimspec.edn files

matching-models

An array of strings defining the set of models with which a Test or Verification Check (VC) is compatible. A setting of 'standard-models' means that the Test/VC is compatible with Portable Models (PMs) and Simulator Models (SM) with run-compatbility set to 'portable-models'. Otherwise matching-models contains a list of Special-Purpose SMs forming a subclass that the Test/VC supports.

Required for: Test and Verication Check

model

The Extended KIM ID of a Portable Model.

  • Results or errors generated by running against a Portable Model must have this key.

Conditionally Required for: Test Result, Error, Verification Result

model-driver

The Model Driver's Extended KIM ID.

If a Portable Model is associated with a Model Driver:

  • The Portable Model must have a model-driver assigned in its kimspec.edn file.

If a Portable Model is not associated with a Model Driver:

  • The Portable Model must not have a model-driver assigned in its kimspec.edn file. Optional for: Model
potential-type

The general potential class to which the model belongs, e.g. eam.

Required for: Model, Simulator Model

properties

A list of properties reported by a KIM Item.

This is an array of strings.

Note:

  • All Test Drivers must have this key.
  • A Test must have this key if it is not associated with a Test Driver.
  • Tests associated with a Test Driver must not have this key.
  • This key is automatically added to Reference Data.

Required for: Test Driver, Verification Check

Conditionally Required for: Test

Optional on submission for Reference Data, will be added to all kimspec.edn files from the Reference Data content

publication-year

Year this item was published on openkim.org.

Note:

  • If a Model or Test is updated to a new version automatically by the system, such as in the case of an updated Driver, the previous publication-year will be kept.

Optional on submission, current year will be added to all kimspec.edn files

run-compatibility

A string defining how a Simulator Model (SM) may be used. A setting of portable-models means that the SM can be used with the same input provided to a Portable Model (PM). A setting of special-purpose-models means that the SM requires input that differs from that of PMs.

Required for: Simulator Model

short-id

Required by: Reference Data

simulator-model

The Extended KIM ID of a Simulator Model.

  • Results or errors generated by running against a Simulator Model must have this key.

Conditionally Required for: Test Result, Error, Verification Result

simulator-name

Name of the simulator, if any, being utilitized by the Test, Test Driver, or Verification Check; for Simulator Models, it is the name of the simulator in which it can function. Examples include LAMMPS, ase, or none.

  • Tests associated with a Test Driver must not have this key.

Required for: Simulator Model, Test Driver, Verification Check

Conditionally Required for: Test

simulator-potential

The simulator-native syntax used to specify the class of the potential, e.g. eam/fs.

Required for: Simulator Model

simulator-potential-compatibility

An array of dictionaries detailing which parameter file formats from different simulators a Model Driver supports. Each dictionary contains up to four keys: simulator-name, simulator-potential, compatibility, and compatibility-notes. The first two keys are required and have the same meaning as elsewhere in kimspec.edn. The compatibility key is also required and describes the extent to which the Model Driver is compatible with a given parameter file format and can be either "full" or "partial". Finally, the compatibility-notes key is optional and consists of free-form text a Model Driver can provide to explain its compatibility with different formats in greater detail, including caveats or requirements. Examples of dictionary entries include:

{"simulator-name" "LAMMPS" "simulator-potential" "eam" "compatibility" "full"}

{"simulator-name" "LAMMPS" "simulator-potential" "eam/alloy" "compatibility" "partial" "compatibility-notes" "Only certain combinations of parameters are supported."}

{"simulator-name" "LAMMPS" "simulator-potential" "tersoff" "compatibility" "partial" "compatibility-notes" "LAMMPS tersoff parameter file format not supported, but a conversion utility is included with this driver."}

Note:

  • This key will be empty or not provided if the Model Driver is not compatible with any simulator's parameter file format for a specific potential.

Optional for: Model Driver

source-citations

An array of BibTeX-style EDN dictionaries corresponding to primary published work(s) describing the KIM Item.

Note:

  • Even a single dictionary must be enclosed in array brackets [].

Required for: Reference Data

Optional for: Model, Simulator Model, Test, Model Driver, Test Driver, Verification Check

species

An array of strings describing the possible atomic species that a KIM Item contains or supports.

Note:

  • If omitted from a Verification Check, it is assumed to support all species.

Required for: Model, Simulator Model, Test, Reference Data

Optional for: Verification Check

test

Required for: Test Result

Conditionally Required for: Error (if the Error was produced by a Test rather than a Verification Check)

test-driver

The relevant Test Driver's Extended KIM ID.

Optional for: Test

test-result-id

Unique identifier associated with a Test Result that contains the Short KIM ID of a Test and a Model, as well as a timestamp.

Example: TE_485755527152_001-and-MO_958932894036_001-1416502690-tr

Required for: Test Result

title

Used when displaying a KIM Item on openkim.org, as well as autogenerating its citation. The title should not include an ending period.

Required by: Model, Simulator Model, Test, Model Driver, Test Driver, Verification Check

verification-check

Required for: Verification Result

Conditionally Required for: Error (if the Error was produced by a Verification Check rather than a Test)

verification-result-id

Unique identifier associated with a Verification Result that contains the Short KIM ID of a Verification Check and a Model, as well as a timestamp.

Example: VC_303890932454_001-and-MO_769582363439_004-1525996165-vr

Required for: Verification Result


Deprecated keys

pipeline-api-version

Version of the pipeline API that this KIM Item is compatible with, expressed as a semantic version string. The pipeline API specifies the name of the executable file of a Test Driver, Test, or Verification Check to be run when it is invoked by the pipeline. It also dictates the name and contents of the template file that is rendered to create the final input file that is piped to it when it is invoked.

Note:

  • All Test Drivers must have this key.
  • A Test must have this key if it is not associated with a Test Driver.
  • Tests associated with a Test Driver must not have this key.
  • This key is automatically added to Reference Data.

Required for: Test Driver, Verification Check

Conditionally Required for: Test


← KIM Properties Framework
kimprovenance.edn Reference →