This schema defines the manner in which Test Drivers (TDs) and Verification Checks (VCs) in openkim.org specify the types of Portable Models (PMs) and Simulator Models (SMs) with which they are compatible. The notion of SM subclasses is defined, which allows a TD or VC to provide specialized input for specific types of SMs. TDs and VCs that support SM subclasses are called "Special Purpose TDs" and "Special Purpose VCs."
The schema includes required keys in kimspec.edn for TDs, VCs, PMs and SMs, and a definition of the matching logic for the OpenKIM Processing Pipeline (PP).
SMs are divided into two categories: (1) Standard SMs that only require information about an atomic configuration available through the KIM API PM standard, and (2) Special-Purpose SMs that require additional information.
The category of an SM is defined by a required run-compatibility key in its kimspec.edn file which contains a single string.
For a Standard SM, the run-compatibility key is set to portable-models.
For a Special-Purpose SM, the run-compatibility key is set to special-purpose-models.
Note that a Standard SM may be able to receive additional information not available through the KIM API PM standard, but if this information is not provided the SM can still work. (An example is an SM that uses charges if provided, but otherwise uses default or internally computed values.)
For the discussion below, we define "Standard Models" to be the set of all PMs and Standard SMs.
Tests and VCs are divided into two categories: (1) Standard Tests/VCs that only work with Standard Models, and (2) Special-Purpose Tests/VCs that work with a subclass of Special-Purpose SMs.
The category of a Test/VC is defined by a required matching-models key in its kimspec.edn file containing an array of strings. This key defines the set of models with which the Test/VC is compatible.
For a Standard Test/VC, the matching-models key can only contain ["standard-models"].
For a Special-Purpose Test/VC, the matching-models key contains a list of Special-Purpose SMs forming a subclass that the Test/VC supports.
A subclass is a set of Special-Purpose SMs that do not need to be distinguished in terms of the input passed from a Test to its TD or for the operation of the VC. An example is a set of bonded force field SMs that use the same input format, or a set of SMs that require charges that are specified in the same format.
A subclass is specified as an array of strings each of which represents an individual SM or a set of related SMs, e.g. ["iff/cvff", "iff/pcff"] or ["iff/"].
A hierarchy notation is used for SM names. Names that do not end with a slash refers to a single SM (e.g. iff refers the potentials of type iff, or iff/cvff refers to potentials of type iff/cvff). Names that end with a slash refer to all SMs within a category (e.g. iff/ refers to all potentials below iff/ in the hierachy (but not including iff), such as iff/cvff, iff/pcff, iff/cvff/long, etc., and further subcategories if they exist.
A subclass cannot contain standard-models as a member.
A subclass is associated with a single Simulator as specified by the simulator-name key in the kimspec.edn file of the Test/VC.
A subclass specifications is local to a particular Special-Purpose Test or VC. The OpenKIM system does not define or track subclasses as an independent concept.
A TD may support Standard Models was well as multiple subclasses of Special-Purpose SMs. However each Test associated with the TD is limited to either Standard Models or a single subclass. (This is done to keep the parameter files associated with an individual Test from becoming unwieldy due to the need to support the requirements of different types of models.) For example if the TD supports both Standard Models and a subclass requiring charges, then the TD would need to have separate Tests for these cases. The Test parameter file would contain information identifying it, for example a key set to either standard or charge, where for charge the parameter file would include additional charge information not provided by the KIM API PM standard.
It is possible for an SM to be a Standard Model and/or belong to more than one subclass. This means that an SM could be run by more than one Test associated with a TD. For example, a Standard SM may also use charges if provided as noted in item 1b. When run by a Standard Test/VC such a model would use default values for charges, but with a Special-Purpose Test/VC it would initialize the charges to provided values. This could lead to some confusion, but it also provides valuable information on the predictions of the SM under different modes of operation. Thus there can be multiple results for a single model (and species) for the same TD.
The PP matching logic for Standard and Special-Purpose SMs consistent with the above points is defined below. (Note that in the following "compatible" means passing additional PP matching criteria such as species, KIM API version, and simulator.)
A compatible Test/VC and Model are considered to match according to the following table:
| Test/VC matching-models list A | PM | SM |
|---|---|---|
| A=["standard-models"] | yes | run-compatibility == "portable-models" |
| A=[...] | no | simulator-potential in A |