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
author 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
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
kim-api-version N/A N/A N/A N/A
maintainer-id 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
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
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.

author

A string listing the name(s) of the creators of the relevant KIM Item's code and/or content. Multiple names should be separated by 'and'.

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

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

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

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

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

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

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