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 External Model Test Result Error Model Verification Test Verification Verification Result
description N/A N/A N/A
disclaimer N/A N/A N/A N/A N/A N/A
doi N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A
domain
executables N/A</i> N/A</i> N/A</i>
extended-id N/A N/A N/A N/A N/A
file-formatting-information N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A
kim-api-version 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 N/A
model-driver N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A
model-verification N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A
notes N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A
pipeline-api-version 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 N/A
short-id 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 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 N/A
test-result-id N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A
test-verification N/A 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 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.

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, Model Verification, Test Verification

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, Model Verification, Test Verification

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

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 by: Model, Test, Model Driver, Test Driver, Model Verification, Test Verification

kim-api-version

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

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

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.

Note:

  • 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

model-verification

The Extended KIM ID of a Model Verification. This would be paired with the key model.

Conditionally Optional or Required for: Verification Result

notes

Miscellaneous notes that may be added to Reference Data.

Optional for: Reference Data

pipeline-api-version

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

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.

Required for: Test Driver

Conditionally Required for: Test

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, Test Verification, Model Verification

Conditionally Required for: Test

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

short-id

Required by: Reference Data

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

species

An ordered array of strings.

The array may contain blank strings ("").

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

test

The Extended KIM ID of a Test.

Required for: Test Result, Error

Conditionally Optional or Required for: Verification Result

test-driver

The Test Driver's Extended KIM ID.

Note:

  • If a Test Driver is associated with the Test:
    • The Test must have a test-driver assigned in its kimspec.edn file.
    • The Test is considered parameterized. The Test can be referred to more specifically as a Parameterized Test.
  • If a Test Driver is not associated with the Test:
    • The Test must not have a test-driver assigned in its kimspec.edn file.
    • The Test is not considered parameterized. The Test can be referred to more specifically as a Stand-alone Test.

Stand-alone vs. Parameterized:

  • A Stand-alone Test is a software implementation of an interatomic test.
  • A Parameterized Test consists of a parameter file to be read in by a Test Driver.

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

Required for: Test Result

test-verification

The Extended KIM ID of a Model Verification. This would be paired with the key test.

Conditionally Optional or Required for: Verification 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, Model Verification, Test Verification