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 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
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
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
model-driver 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
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
simulator-name 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
test-driver 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
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
verification-result-id 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, 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, 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, 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, Test, Model Driver, Test Driver, Verification Check

doi

The digital object identifier associated with the KIM Item.

Optional on submission for 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_Ercolessi_Adams_Al__MO_123629422045_000

Required for: 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, 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 Model.

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
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-name

Name of the simulator, if any, being utilitized by the Test, Test Driver, or Verification Check. Example include LAMMPS, ase, or none.

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

Required for: Test, Test Driver, Verification Check

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, 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, 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, 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