A question about KIM pipeline

Hi

I have two question about KIM pipeline when I was creating Test Driver and Tests.

  1. I am wondering is it necessary to include ‘descriptor.kim’ and ‘kimspec.edn’ in the TE directory? Do these files really work?
  2. Since the Makefile is doing nothing, can we just delete it?

Thank you!

Best,
Jiadi

Hi Jiadi,

I have two question about KIM pipeline when I was creating Test Driver and Tests.

  1. I am wondering is it necessary to include ‘descriptor.kim’ and ‘kimspec.edn’ in the TE directory? Do these files really work?

Yes, both of them are necessary.

(I) Every Model and every Test are required to have a file named descriptor.kim for the KIM API to interpret. The descriptor.kim files for both Models and Tests list a number of pieces of essential information that define what they are in the KIM ecosystem, including:

a.) what version of the KIM API they are designed to work with.

b.) what the native units are that they use. This is important because the API has to be able to allow a Model that uses one set of units to work with a Test that uses a completely different set of units. When it does this, the API automatically converts between the two sets of units when it passes information between the Model and the Test.

c.) which atomic species they can work with under the “SUPPORTED_ATOM/PARTICLES_TYPES” section

d.) which neighbor list methods they support under the “CONVENTIONS” section

e.) In the case of Tests, what type of information they are able to provide to a Model. This falls under the “MODEL_INPUT” section. The “MODEL_OUTPUT” section lists what information they require any Model they run with to be able to provide.

All of this information is necessary in order for the pipeline to be able to use the KIM API to automatically try to run a Test with a Model. If the descriptor.kim files are not compatible according to the KIM API, then the Test-Model pair cannot be run, e.g. a Test designed only to perform calculations on carbon could never run with a Model that only defines a potential for silicon. However, if the descriptor.kim files are compatible according to the KIM API, then the Test-Model pair is run, e.g. a Test which performs calculations on carbon has no problem running with a Model that supports both carbon and silicon.

(II) Moreover, every KIM Item, whether it be a Model, Model Driver, Test, Test Driver, or Reference Data, is also required to have a kimspec.edn file. This file is used for two purposes:

a.) First, it contains necessary information for the pipeline. An example is the KIM API version that the item is intended to work with (which is important for any KIM Item aside from Reference Data). Another example is the case of a Test that uses a Test Driver: the only place where a Test like this will list which Test Driver it needs to use is in the kimspec file under the ‘test-driver’ key. The same is true of Models that use Model Drivers.

b.) The kimspec.edn files also contain metadata which is used to create the KIM Items pages you see on openkim.org. For instance, if you look at the page for the EDIP potential I uploaded (click here) and you scroll down to Files and open up its kimspec.edn, you’ll see that this information is precisely what was used to fill out the fields at the top of this web page.

  1. Since the Makefile is doing nothing, can we just delete it?

Originally, the pipeline always required a Makefile to accompany every Model/Model Driver/Test/Test Driver as part of its standard way of importing these objects. However, it was changed so that now, a Makefile is no longer required if your code is interpreted rather than compiled.

Cheers,

Dan

e.) In the case of Tests, what type of information they are able to provide to a Model. This falls under the “MODEL_INPUT” section. The “MODEL_OUTPUT” section lists what information they require any Model they run with to be able to provide.

I forgot to mention here that, conversely, the descriptor.kim file of a Model describes the inputs the Model requires from a Test under the “MODEL_INPUT” section and the outputs the Model can provide to a Test under the “MODEL_OUTPUT” section.

Dan

I’d like to add to my original reply that the KIM descriptor file (KDF) of a Model no longer has to be named “descriptor.kim” in recent versions of the KIM API. Indeed, you can find the following in the update notes (the ‘NEWS’ file included with the API tarball) for any version 1.6.0 or later of the KIM API:

* Model “.kim” file name is now specified in the Makefile and can be anything
the developer desires.

Moreover, if a Model uses a Model Driver, it actually doesn’t need to have its own KDF. Rather, since the Model Driver corresponding to such a Model is specified in the Model’s Makefile, the convention is actually to create a KDF template file along with the Model Driver. Models derived from it will then automatically use a suitable version of it with the appropriate species filled in. There’s a related remark in the API version 1.6.0 update notes:

* Model Drivers now specify the name of their “.kim” file template in their
Makefile. The conventional name for these files now ends in “.kim.tpl”.

Dan