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
content-origin N/A N/A N/A
content-other-locations 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
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
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
potential-type N/A 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
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

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.

content-origin

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

content-other-locations

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

data-method

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

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

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

model

The Extended KIM ID of a Model.

Required for: Test Result, Error

Conditionally Optional or Required for: 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 Stand-alone Model.

Stand-alone vs. Parameterized:

  • A Stand-alone 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

potential-type

properties

A list of properties used.

This is an array of strings.

Note:

  • All Test Drivers must have this key.
  • Tests must have this key if they are a Stand-alone Tests. A Stand-alone Test 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

Optional for: Test, Test Driver, Verification Check

source-citations

A citation to primary published work(s) describing the KIM Item. Multiple source citations should be separated by blank lines.

Required for: Reference Data

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

species

An ordered array of strings.

Optional for: Model, Test, Reference Data, Model Verification, Test Verification

test

Required for: Test Result, Error

Conditionally Optional or Required for: Verification Result

test-driver

The Test Driver's Extended KIM ID.

Optional for: Test

test-result-id

An identifier for Test Results that contains the Short KIM ID of the Test and Model, and a unique timestamp.

Example: TE_485755527152_001-and-MO_958932894036_001-1416502690-tr

Required for: Test Result

title

The title will be used in citations of the property. The title should not include an ending period.

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