kimspec.edn Content Guide

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

Quick reference table
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 IPRP 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 Model Driver is associated with the Model:

  • The Model must have a model-driver assigned in its kimspec.edn file.
  • The Model is considered parameterized. The Model can be referred to more specifically as a Parameterized Model.

If a Model Driver is not associated with the Model:

  • The Model must not have a model-driver assigned in its kimspec.edn file.
  • The Model is not considered parameterized. The Model can be referred to more specifically as a Standalone Model.

Standalone vs. Parameterized:

  • A Standalone Model is a software implementation of an interatomic model.
  • A Parameterized Model consists of a parameter file to be read in by a Model Driver.

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.
  • Tests must have this key if they are a Standalone Tests (a Standalone Test is one that 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