Tutorial on Developing KIM Tests using ASE

Test | Example Calculation


Test

Here, we describe a very basic Test using the Atomic Simulation Environment (ASE), ASECohesiveEnergyFromQueryExample_fcc_Ar__TE_102111117114_002. This Test is designed to (1) retrieve the equilibrium FCC lattice constant for Argon for whichever Model it is being run against by querying the OpenKIM Repository and (2) calculate the cohesive energy corresponding to this lattice constant for that Model.


List of files

Along with a LICENSE file and README, we have the six files that are required to be a valid KIM test in the repository:

  • runner - the main executable, a Python script
  • pipeline.stdin.tpl - Jinja template file to provide input on stdin
  • dependencies.edn - specifies other Tests that this Test depends on
  • descriptor.kim - KIM descriptor file which determines whether the Test is compatible with a given KIM Model
  • kimspec.edn - metadata file that describes our Test (used by the OpenKIM system)
  • Makefile - trivial makefile (does nothing since no compilation is needed)
  • README.md - brief description of the Test
  • LICENSE.CDDL - a copy of the CDDL license

runner

This is a standalone Python script that takes as input the name of a KIM Model and the corresponding FCC argon lattice constant it predicts and computes the corresponding cohesive energy.

#!/usr/bin/env python
"""
ASE cohesive energy example test with dependencies

Date: 2014/08/05
Author: Matt Bierbaum

Updated 2018/07/10 by Daniel S. Karls (the latest ASE uses ase.build rather than ase.structure)
"""
from ase.build import bulk
from kimcalculator import KIMCalculator
from string import Template
import os

#grab from stdin (or a file)
model = raw_input("modelname=")
lattice_constant = raw_input("lattice constant=")
lattice_constant = 10**10 * float(lattice_constant)

# calculate the cohesive energy
calc = KIMCalculator(model)
slab = bulk('Ar', 'fcc', a=lattice_constant)
slab.set_calculator(calc)
energy = -slab.get_potential_energy()

# pack the results in a dictionary
results = {'lattice_constant': lattice_constant,
            'cohesive_energy': energy}

output = Template("""
[{
    "property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-potential-energy-cubic-crystal"
    "instance-id" 1
    "short-name" {
        "source-value"  ["fcc"]
    }
    "species" {
        "source-value"  ["Ar"]
    }
    "a" {
        "source-value"  $lattice_constant
        "source-unit"   "angstrom"
    }
    "basis-atom-coordinates" {
        "source-value"  [[0.0 0.0 0.0] [0.0 0.5 0.5] [0.5 0.0 0.5] [0.5 0.5 0.0]]
    }
    "space-group" {
        "source-value"  "Fm-3m"
    }
    "cohesive-potential-energy" {
        "source-value"  $cohesive_energy
        "source-unit"   "eV"
    }
}]""").substitute(**results)

with open(os.path.abspath("output/results.edn"), "w") as f:
    f.write(output)

The Test begins by grabbing the KIM Model name and lattice constant from stdin (cf. the section for pipeline.stdin.tpl below). It assumes that the lattice constant will be input in SI units and converts it to angstroms. Next, it initializes an instance of the KIM ASE calculator using the inputted Model name. Using the provided lattice constant, it then sets up a primitive FCC Ar unit cell with periodic boundary conditions and invokes the get_potential_energy function of the ASE calculator. Since the primitive FCC unit cell contains only a single atom, there's no need to divide by the number of atoms to get the cohesive energy. Finally, the results are packed into a dictionary corresponding to the latest version of the relevant KIM Property Definition, tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-potential-energy-cubic-crystal.1, 2 The name of the file that results are written to, results.edn, is a convention all KIM Tests are required to follow. The location of this file is the 'output' directory, which the OpenKIM Processing Pipeline automatically creates inside of the temporary directory where it will run the Test against a given Model; everything placed inside of the 'output' directory is retained in the results of the Test, while everything that is not is discarded.

1 To learn more about KIM Property Definitions, see the KIM Properties Framework.

2 To see a list of all current KIM Property Definitions, click here.

Note

Every KIM Test and Test Driver is required to have a primary executable named 'runner', although this executable is free to call other executables, etc.


pipeline.stdin.tpl

This is a Jinja2-formatted template file that the OpenKIM Processing Pipeline will fill in and provide to the Test on stdin when it is run against a Model.

@< MODELNAME >@
@< query({
    "project": ["a.si-value"],
    "query": {
        "property-id": "tag:staff@noreply.openkim.org,2014-04-15:property/structure-cubic-crystal-npt",
        "short-name.source-value": "fcc",
        "meta.subject.kimcode": MODELNAME,
        "meta.runner.kimcode": {"$options": "", "$regex": "LatticeConstantCubicEnergy_fcc_Ar__TE_206669103745"}
    },
    "limit": 1,
    "database": "data"
}) >@

The pipeline's custom Jinja environment features the notation @<…>@ for enclosing python code you wish to execute, while @[…]@ denotes code blocks and @#…#@ denotes comments. Many standard Python functions can thus be used inside of @<…>@ delimiters, as well as a few special functions and keywords specific to KIM. On the first line, the special keyword MODELNAME will be replaced by the name of the Model that the pipeline is currently running the Test against. The remainder of the file is interpreted as a single line since it consists of a single @<…>@ statement, and contains a call to the special function query(). This function effectively allows the Test to retrieve already-computed Test Results from the OpenKIM Repository, and follows a special set of semantics established by the pipeline when storing results (namely the "meta.subject.kimcode" and "meta.runner.kimcode" attributes seen above, which the pipeline uses to record the Model and Test/Verification Check used to compute a given result or error). This specific query retrieves the lattice constant computed for the current Model by the latest version of the Test named LatticeConstantCubicEnergy_fcc_Ar__TE_206669103745; at this time, the latest version is LatticeConstantCubicEnergy_fcc_Ar__TE_206669103745_004. To aid in constructing queries, a web interface has been established which allows either raw queries as done above or a simplified interface function called get_test_result().

Note

Every KIM Test requires a file named pipeline.stdin.tpl which, if nothing else, is used to input the name of the KIM Model currently being run against.


dependencies.edn

This file is used internally by the pipeline to ensure that Tests are run in the appropriate order. It should simply contain a listing of any other Tests that show up in the pipeline.stdin.tpl queries. Generally speaking, Tests should only query for the results of the latest versions of other Tests, so the 3-digit version extension is usually omitted. The full names of dependencies can also be omitted, as done below. In this case, there is only a single dependency: LatticeConstantCubicEnergy_fcc_Ar__TE_206669103745_004. Multiple dependencies are separated by spaces (see About the EDN data format).

[ "TE_206669103745" ]

descriptor.kim

This file is used by the KIM API to determine which Models this Test is compatible with. Note that this file will not be present in the next version of this Test which will be written so as to be compliant with KIM API v2.0. (For a complete list of changes that will be occurring in changing from KIM API v1.X to KIM API v2.0, see here.)


Example Calculation

On the OpenKIM User VM (available on openkim.org soon), this Test can be installed using the kimitems utility:

kimitems install ASECohesiveEnergyFromQueryExample_fcc_Ar__TE_102111117114_002

which will download a tarball of the Test from openkim.org, decompress it into ~/openkim-repository/te/, and attempt to build it.

Suppose we now wish to run this Test against Pair_Lennard_Jones_Shifted_Bernardes_MedCutoff_Ar__MO_126566794224_002. After installing the Model via

kimitems install Pair_Lennard_Jones_Shifted_Bernardes_MedCutoff_Ar__MO_126566794224_002

we can run this specific Test-Model pair by issuing

pipeline-run-pair ASECohesiveEnergyFromQueryExample_fcc_Ar__TE_102111117114_002 Pair_Lennard_Jones_Shifted_Bernardes_MedCutoff_Ar__MO_126566794224_002

This will result in output like this:

+ Running pair (ASECohesiveEnergyFromQueryExample_fcc_Ar__TE_102111117114_002, Pair_Lennard_Jones_Shifted_Bernardes_MedCutoff_Ar__MO_126566794224_002)

  Pair produced Test Result TE_102111117114_002-and-MO_126566794224_002-1531507061-tr in 0.20717191696166992 seconds

This indicates that our Test-Model pair produced a Test Result (as opposed to an Error), and that the corresponding directory was placed in ~/openkim-repository/tr/TE_102111117114_002-and-MO_126566794224_002-1531507061-tr. Let's go to this folder and inspect its contents:

~/openkim-repository/tr/TE_102111117114_002-and-MO_126566794224_002-1531507061-tr
├── kim.log - log file created by the KIM API
├── kimspec.edn - metadata for the Test Result
├── pipeline.stderr - stderr output from the Test
├── pipeline.stdin - final stdin that was fed to the Test
├── pipeline.stdin.info - information about which Test Results in the OpenKIM Repository were matched on by the queries in pipeline.stdin.tpl
├── pipeline.stdout - stdout output from the Test
├── pipelinespec.edn - profiling information, including runtime
└── results.edn - final results file output by the Test

If we take a look at the pipeline.stdin file, we can see that the query contained in pipeline.stdin.tpl was successfully rendered to the string "5.24850907922e-10":

Pair_Lennard_Jones_Shifted_Bernardes_MedCutoff_Ar__MO_126566794224_002
5.24850907922e-10

and from results.edn, we see that the cohesive energy computed by the Test was approximately 0.0865 eV:

[
    {
        "short-name" {
            "source-value" [
                "fcc"
            ]
        }
        "a" {
            "si-unit" "m"
            "source-unit" "angstrom"
            "si-value" 5.24850907922e-10
            "source-value" 5.24850907922
        }
        "property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-potential-energy-cubic-crystal"
        "space-group" {
            "source-value" "Fm-3m"
        }
        "cohesive-potential-energy" {
            "si-unit" "kg m^2 / s^2"
            "source-unit" "eV"
            "si-value" 1.38597103281265e-20
            "source-value" 0.08650550849505412
        }
        "basis-atom-coordinates" {
            "source-value" [
                [
                    0.0
                    0.0
                    0.0
                ]
                [
                    0.0
                    0.5
                    0.5
                ]
                [
                    0.5
                    0.0
                    0.5
                ]
                [
                    0.5
                    0.5
                    0.0
                ]
            ]
        }
        "species" {
            "source-value" [
                "Ar"
            ]
        }
        "instance-id" 1
    }
]

Note

Don't waste your time typing when you don't have to! Tab-completion is supported over the KIM VM command-line utility names, their options, and currently installed KIM Tests, Models, Verification Checks, etc.

Note

To run this Test against all compatible Models currently installed on your KIM VM, you can issue pipeline-run-matches ASECohesiveEnergyFromQueryExample_fcc_Ar__TE_102111117114_002.

Note

Although not so useful here, the -v/--verbose flag to pipeline-run-pair and pipeline-run-matches prints the stdout and stderr streams of the Test to the terminal while it is running.