Using the KIM Developer Platform

The KIM Developer Platform is a Docker container image that provides a preconfigured linux environment for interactively compiling and executing tests, verification checks, models, and simulator models from OpenKIM against one another just as they would run inside of the OpenKIM Processing Pipeline that generates the the results displayed on openkim.org. This includes a gcc compiler toolchain, molecular simulation software (LAMMPS and ASE), and a convenient set of command line utilities that are adapted to the structure of OpenKIM content. The resulting environment is useful for anyone planning on developing models or tests to submit to OpenKIM or who simply wants to run KIM verification checks to validate the integrity of their own models. Below, we walk through using the KIM Developer Platform to download and run a verification check and a test against a specific model.

For instructions on installing the KIM Developer Platform, see https://github.com/openkim/developer-platform.

A public Binder instance of the KIM Developer Platform with additional interactive tutorials is available here. Due to non-persistence and potential reliability issues, it should be viewed as a demo, not a place for serious development.


Contents of the home directory

After starting the KIM Developer Platform container and connecting to it, you will find the following in the home directory:

~
├── README.txt - Description of command line utilities and basic usage patterns
├── errors - Errors generated by jobs
├── model-drivers - KIM Model Drivers
├── models - KIM Portable Models
├── simulator-models - KIM Simulator Models
├── test-drivers - KIM Test Drivers
├── test-results - Results generated by jobs involving Tests
├── tests - KIM Tests
├── verification-checks - KIM Verification Checks
└── verification-results - Results generated by jobs involving Verification Checks

In each of these directories, each KIM test, model, etc, that you download or create will have its own individual directory named for its extended KIM ID.


Installing a model and verification check

Downloading, compiling, and installing tests, models, etc., can be done using the kimitems command line utility.1 In order to install Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004, we can execute kimitems with the install subcommand, which will download, compile, and install it:

openkim@fa2c181e2c6b:~$ kimitems install -a Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004
Notice: Item Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004 requires a driver (Tersoff_LAMMPS__MD_077075034781_005) to work. Would you like to install the driver? [y/n]
y
Downloading Tersoff_LAMMPS__MD_077075034781_005...
Installing Tersoff_LAMMPS__MD_077075034781_005 to /home/openkim/model-drivers/Tersoff_LAMMPS__MD_077075034781_005...
Downloading Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004...
Installing Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004 to /home/openkim/models/Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004...
Building Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004...
openkim@fa2c181e2c6b:~$

Since this model requires a model driver that was not already installed inside the container, we were prompted to install it. If we now list the contents in the home directory, we will see that the model and model driver were both installed:

openkim@fa2c181e2c6b:~$ tree -L 3
.
├── README.txt
├── errors
├── model-drivers
│   └── Tersoff_LAMMPS__MD_077075034781_005
│       ├── CMakeLists.txt
│       ├── LICENSE
│       ├── README
│       ├── build
│       ├── helpers
│       ├── kimcite-MD_077075034781_005.bib
│       ├── kimprovenance.edn
│       ├── kimspec.edn
│       ├── model_driver_Tersoff.cpp
│       ├── ndarray.hpp
│       ├── pair_tersoff.cpp
│       ├── pair_tersoff.hpp
│       ├── pair_tersoff_zbl.cpp
│       └── pair_tersoff_zbl.hpp
├── models
│   └── Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004
│       ├── CMakeLists.txt
│       ├── LICENSE
│       ├── Tersoff_1988T2_Si.params
│       ├── Tersoff_1988T2_Si.settings
│       ├── build
│       ├── kimcite-MO_245095684871_004.bib
│       ├── kimprovenance.edn
│       └── kimspec.edn
├── simulator-models
├── test-drivers
├── test-results
├── tests
├── verification-checks
└── verification-results

The 'build' subdirectories of the model and model driver are used by cmake as a temporary place to compile them and contain the resulting binaries. These subdirectories are left in place after compilation so that the cmake cache can be reused if any changes are made to the items. The kimitems install command also installed the binaries into the KIM API User Collection, which we can verify by using the KIM API collections management utility:

openkim@fa2c181e2c6b:~$ kim-api-collections-management list


Knowledgebase of Interatomic Models (KIM)  ---  Model Collections Listing
===============================================================================

kim-api :
	kim-api 2.2.1+GNU.GNU.GNU
kim-api-uid :
	2.2.1+GNU.GNU.GNU.2021-06-18-03-57-47

kim-api configuration file:
	/home/openkim/.kim-api/2.2.1+GNU.GNU.GNU.2021-06-18-03-57-47/config
.
.
.
User Collection
-------------------------------------------------------------------------------
Model Drivers: '/home/openkim/.kim-api/2.2.1+GNU.GNU.GNU.2021-06-18-03-57-47/model-drivers-dir'
	Tersoff_LAMMPS__MD_077075034781_005

Portable Models: '/home/openkim/.kim-api/2.2.1+GNU.GNU.GNU.2021-06-18-03-57-47/portable-models-dir'
	Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004

Simulator Models: '/home/openkim/.kim-api/2.2.1+GNU.GNU.GNU.2021-06-18-03-57-47/simulator-models-dir'
	--empty--
.
.
.

Now that the model and its driver are installed, they can run with a test or verification check. In order to retrieve a listing of the latest versions of all verification checks in the OpenKIM repository, we can use the kimitems search command with the -t flag, which queries based on item type—in this case, 'vc' for verification check. Since we want to see all verification checks, the search term we pass to the command is .*, which in regular expression syntax means that any string will be a match:

openkim@fa2c181e2c6b:~$ kimitems search -t vc .*
DimerContinuityC1__VC_303890932454_004
ForcesNumerDeriv__VC_710586816390_003
InversionSymmetry__VC_021653764022_002
MemoryLeak__VC_561022993723_003
Objectivity__VC_813478999433_002
PeriodicitySupport__VC_895061507745_002
PermutationSymmetry__VC_903502816694_002
SpeciesSupportedAsStated__VC_651200051721_002
ThreadSafety__VC_881176209980_005
UnitConversion__VC_128739598203_000
openkim@fa2c181e2c6b:~$

For this example, we will install the ForcesNumerDeriv__VC_710586816390_003 verification check, again using kimitems install:

openkim@fa2c181e2c6b:~$ kimitems install ForcesNumerDeriv__VC_710586816390_003
Downloading ForcesNumerDeriv__VC_710586816390_003...
Installing ForcesNumerDeriv__VC_710586816390_003 to /home/openkim/verification-checks/ForcesNumerDeriv__VC_710586816390_003...
Building ForcesNumerDeriv__VC_710586816390_003...
openkim@fa2c181e2c6b:~$

Similar to the models, we can verify that the verification check has been installed under the ~/verification-checks/ directory:

kim@fa2c181e2c6b:~$ ls ~/verification-checks/
ForcesNumerDeriv__VC_710586816390_003
openkim@fa2c181e2c6b:~$

Running the verification check against the model

Now that the verification check and model are installed, we can run them together by using one of the pipeline-run-* utilities. In this case, since we only want to run a single pair of items against one another, we can use pipeline-run-pair. In order to see the output of the verification check in real time as it runs, we can pass the -v (or --verbose) option:2

openkim@fa2c181e2c6b:~$ pipeline-run-pair -v ForcesNumerDeriv__VC_710586816390_003 Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004
+ Running pair (ForcesNumerDeriv__VC_710586816390_003, Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004)

Model Extended KIM ID =
=== Verification check vc-forces-numerical-derivative start (2021-06-19 18:31:22) ===
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!                                                      !!!!!
!!!!!  VERIFICATION CHECK: vc-forces-numerical-derivative  !!!!!
!!!!!                                                      !!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Description: Comparison of the analytical forces obtained from the model with
             forces computed by numerical differentiation using Richardson
             extrapolation for a randomly distorted non-periodic structure based
             off the equilibrium face-centered cubic (fcc) structure. Separate
             configurations are tested for each species supported by the model,
             as well as one containing a random distribution of all species.
             Configurations used for testing are provided as auxiliary files.

Author: Ellad Tadmor

-----------------------------------------------------------------------------------------------------
Results for KIM Model      : Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004
Supported species          : Si

random seed                = 13
perturbation amplitude     = 0.250
number unit cells per side = 2
-----------------------------------------------------------------------------------------------------

Comparison of analytical forces obtained from the model, the force computed as a numerical derivative
of the energy, the difference between them, and the uncertainty in the numerical estimate of the force.
The computed equilibrium lattice constant for the crystal (a0) is given in the heading.

MONOATOMIC STRUCTURE -- Species = Si | a0 = 3.8605337142944336 | (Configuration in file "config-Si.xyz")
-----------------------------------------------------------------------------------------------------
  Part  Spec Dir               Force_model               Force_numer    |Force diff|     uncertainty
-----------------------------------------------------------------------------------------------------
     1  Si     1     1.945641401951425e+00     1.945641401949652e+00     1.77347e-12     5.39111e-11
               2     1.292410105488504e+00     1.292410105486701e+00     1.80367e-12     1.02792e-10
               3     1.409814058586853e+00     1.409814058596158e+00     9.30500e-12     7.33411e-11
-----------------------------------------------------------------------------------------------------
     2  Si     1    -1.241196804866494e+00    -1.241196804849372e+00     1.71219e-11     2.01088e-10
               2    -7.172019132173357e-01    -7.172019132073054e-01     1.00303e-11     5.56488e-12
               3     2.665580676101079e+00     2.665580676102462e+00     1.38378e-12     7.38831e-11
-----------------------------------------------------------------------------------------------------
     3  Si     1    -1.527782863854294e+00    -1.527782863849148e+00     5.14655e-12     1.69051e-11
               2     1.775880066754146e+00     1.775880066758107e+00     3.96150e-12     1.22451e-10
               3    -2.017939759239573e+00    -2.017939759236638e+00     2.93499e-12     2.47207e-11
-----------------------------------------------------------------------------------------------------
     4  Si     1     2.587947108392384e+00     2.587947108397386e+00     5.00266e-12     4.44458e-11
               2    -6.299117459208420e-01    -6.299117459159825e-01     4.85945e-12     1.65717e-11
               3    -3.119601662215755e-02    -3.119601662216529e-02     7.74034e-15     7.01009e-10 *
-----------------------------------------------------------------------------------------------------
     5  Si     1     4.003818264431067e-01     4.003818264438874e-01     7.80764e-13     1.74573e-11
               2     1.967081941294976e+00     1.967081941293660e+00     1.31606e-12     3.43803e-11
               3     1.313141443945106e+00     1.313141443943717e+00     1.38889e-12     2.82130e-12
-----------------------------------------------------------------------------------------------------
     6  Si     1    -2.217694155732422e+00    -2.217694155743786e+00     1.13638e-11     7.31748e-11
               2    -1.127692834361408e+00    -1.127692834362527e+00     1.11910e-12     2.03408e-10
               3     1.967387911780579e+00     1.967387911785071e+00     4.49218e-12     1.13594e-10
-----------------------------------------------------------------------------------------------------
     7  Si     1    -1.121291436214348e-01    -1.121291436189284e-01     2.50634e-12     3.16480e-11
               2    -4.112550560345479e-01    -4.112550560383432e-01     3.79530e-12     2.62969e-11
               3    -1.997665561185326e+00    -1.997665561186614e+00     1.28786e-12     8.34481e-11
-----------------------------------------------------------------------------------------------------
     8  Si     1    -7.136059736714007e-01    -7.136059736664743e-01     4.92639e-12     4.46829e-11
               2    -2.063912763842852e+00    -2.063912763862227e+00     1.93747e-11     5.05835e-10 *
               3    -1.553349658722966e+00    -1.553349658706068e+00     1.68989e-11     1.48438e-10
-----------------------------------------------------------------------------------------------------
     9  Si     1     1.014260766683321e+00     1.014260766681703e+00     1.61826e-12     2.32376e-11
               2    -4.252162288002859e-01    -4.252162288095622e-01     9.27630e-12     1.05994e-10
               3     2.072000852922518e+00     2.072000852919631e+00     2.88702e-12     4.41247e-12
-----------------------------------------------------------------------------------------------------
    10  Si     1    -2.291924820845932e+00    -2.291924820842908e+00     3.02380e-12     2.26352e-11
               2    -6.355269219731583e-01    -6.355269219730530e-01     1.05249e-13     9.91437e-11
               3    -6.686228063535776e-01    -6.686228063587369e-01     5.15932e-12     1.10489e-11
-----------------------------------------------------------------------------------------------------
    11  Si     1    -1.104902551970682e+00    -1.104902551968881e+00     1.80123e-12     3.89007e-11
               2    -1.292201900365975e+00    -1.292201900370322e+00     4.34786e-12     1.30266e-10
               3    -1.571890482119156e+00    -1.571890482118515e+00     6.41265e-13     1.78020e-11
-----------------------------------------------------------------------------------------------------
    12  Si     1     6.927010900457041e-01     6.927010900466014e-01     8.97282e-13     3.65744e-11
               2    -1.292411126635778e+00    -1.292411126633629e+00     2.14895e-12     3.33789e-11
               3    -1.776043117704058e+00    -1.776043117699604e+00     4.45399e-12     3.10265e-11
-----------------------------------------------------------------------------------------------------
    13  Si     1    -1.180030638626023e-02    -1.180030638080245e-02     5.45778e-12     4.89418e-11
               2    -1.433073926351058e+00    -1.433073926359367e+00     8.30913e-12     7.71059e-11
               3    -3.357534943108861e+00    -3.357534943109870e+00     1.00853e-12     1.05742e-11
-----------------------------------------------------------------------------------------------------
    14  Si     1    -1.473070670056122e+00    -1.473070670053894e+00     2.22777e-12     2.47240e-11
               2    -1.320210901826449e+00    -1.320210901824530e+00     1.91869e-12     6.64824e-12
               3     1.184402082532630e+00     1.184402082532639e+00     8.88178e-15     4.31910e-11
-----------------------------------------------------------------------------------------------------
    15  Si     1     2.064973295206656e+00     2.064973295204737e+00     1.91891e-12     1.51252e-11
               2     1.963339395343896e+00     1.963339395337457e+00     6.43863e-12     2.01374e-11
               3     1.481586784554666e+00     1.481586784558074e+00     3.40727e-12     7.44567e-11
-----------------------------------------------------------------------------------------------------
    16  Si     1     1.576008783077148e+00     1.576008783066631e+00     1.05169e-11     6.52720e-11
               2     2.619996948150155e+00     2.619996948145366e+00     4.78861e-12     7.35589e-12
               3     2.259193713933134e+00     2.259193713949452e+00     1.63176e-11     3.16227e-11
-----------------------------------------------------------------------------------------------------
    17  Si     1     1.114847682170540e+00     1.114847682163289e+00     7.25064e-12     1.17910e-10
               2     1.604904754307374e+00     1.604904754305693e+00     1.68154e-12     6.70597e-12
               3     1.239661096028996e-01     1.239661096035053e-01     6.05668e-13     1.59706e-10
-----------------------------------------------------------------------------------------------------
    18  Si     1    -2.465120998917946e-01    -2.465120998940022e-01     2.20760e-12     7.34648e-11
               2     1.413785641112582e-01     1.413785641072700e-01     3.98817e-12     2.00547e-10
               3     4.925425215297123e-02     4.925425213603605e-02     1.69352e-11     4.23771e-10
-----------------------------------------------------------------------------------------------------
    19  Si     1    -1.640825249089171e+00    -1.640825249086864e+00     2.30682e-12     1.23045e-10
               2     1.901652029316529e+00     1.901652029322174e+00     5.64482e-12     3.61426e-11
               3    -7.796161325031166e-02    -7.796161323539245e-02     1.49192e-11     4.07219e-11
-----------------------------------------------------------------------------------------------------
    20  Si     1     1.792146580829790e+00     1.792146580836509e+00     6.71929e-12     1.94200e-11
               2    -1.756954995845992e+00    -1.756954995823284e+00     2.27085e-11     1.50240e-10
               3    -1.812705987167970e+00    -1.812705987175994e+00     8.02469e-12     2.13956e-10
-----------------------------------------------------------------------------------------------------
    21  Si     1     1.221942352738887e+00     1.221942352731551e+00     7.33547e-12     2.15068e-11
               2     1.818369989022316e+00     1.818369989006055e+00     1.62608e-11     1.29930e-10
               3     7.297937138778883e-01     7.297937138755859e-01     2.30238e-12     4.37397e-11
-----------------------------------------------------------------------------------------------------
    22  Si     1    -4.630038665595662e-02    -4.630038638481838e-02     2.71138e-10     7.99140e-10 *
               2    -5.551941138258674e-01    -5.551941138348724e-01     9.00502e-12     1.93067e-09 *
               3     1.183194996048796e+00     1.183194996042178e+00     6.61804e-12     1.41851e-11
-----------------------------------------------------------------------------------------------------
    23  Si     1    -2.928466796390440e+00    -2.928466796387524e+00     2.91633e-12     3.87645e-11
               2     2.116115314811426e+00     2.116115314806065e+00     5.36149e-12     1.53919e-10
               3    -1.663085156261128e+00    -1.663085156260725e+00     4.03011e-13     2.76114e-10
-----------------------------------------------------------------------------------------------------
    24  Si     1     2.118163983236816e+00     2.118163983247539e+00     1.07230e-11     2.32387e-09 *
               2    -1.059176644738180e+00    -1.059176644722849e+00     1.53311e-11     3.50047e-11
               3    -2.119842048450499e+00    -2.119842048458980e+00     8.48077e-12     3.33255e-10
-----------------------------------------------------------------------------------------------------
    25  Si     1    -7.640007179179223e-01    -7.640007179183164e-01     3.94018e-13     4.20830e-11
               2     1.280137126394440e+00     1.280137126403450e+00     9.00924e-12     1.77376e-11
               3     2.901446957920404e+00     2.901446957942845e+00     2.24416e-11     1.54184e-10
-----------------------------------------------------------------------------------------------------
    26  Si     1    -1.698542007871276e+00    -1.698542007868776e+00     2.50022e-12     7.43430e-11
               2     2.530682889687796e+00     2.530682889693203e+00     5.40634e-12     3.51723e-11
               3     1.134057891341194e+00     1.134057891339474e+00     1.72040e-12     5.22928e-11
-----------------------------------------------------------------------------------------------------
    27  Si     1     5.017304843746975e-01     5.017304843658495e-01     8.84792e-12     7.06984e-11
               2    -1.119526803572822e+00    -1.119526803582179e+00     9.35718e-12     4.38021e-11
               3     8.164176092380946e-01     8.164176092179027e-01     2.01918e-11     5.58809e-11
-----------------------------------------------------------------------------------------------------
    28  Si     1     1.291289529807607e+00     1.291289529807266e+00     3.41283e-13     4.00653e-11
               2    -1.513740196668406e+00    -1.513740196692037e+00     2.36311e-11     1.25560e-10
               3    -3.636316190746005e+00    -3.636316190752925e+00     6.92024e-12     1.93045e-10
-----------------------------------------------------------------------------------------------------
    29  Si     1     2.643481027586861e+00     2.643481027058338e+00     5.28523e-10     9.18967e-07 *
               2    -9.607262707279832e-01    -9.607262708036503e-01     7.56670e-11     4.56610e-07 *
               3     1.855992546639207e+00     1.855992546639592e+00     3.85691e-13     1.76688e-11
-----------------------------------------------------------------------------------------------------
    30  Si     1    -4.629076374488803e-01    -4.629076374632280e-01     1.43477e-11     1.62249e-10
               2    -2.462227441985444e+00    -2.462227441977963e+00     7.48068e-12     4.41762e-11
               3     5.004416810139600e-02     5.004416811945343e-02     1.80574e-11     6.06129e-11
-----------------------------------------------------------------------------------------------------
    31  Si     1    -2.200716528831178e+00    -2.200716528834362e+00     3.18412e-12     1.19775e-11
               2     9.517663368700962e-01     9.517663368745909e-01     4.49474e-12     1.26162e-09 *
               3    -9.172070457883466e-01    -9.172070457931000e-01     4.75342e-12     1.67243e-11
-----------------------------------------------------------------------------------------------------
    32  Si     1    -2.831371974432878e-01    -2.831371974344546e-01     8.83316e-12     7.11165e-11
               2    -1.187553674858533e+00    -1.187553674856380e+00     2.15383e-12     1.72258e-11
               3     4.084617440504923e-03     4.084617440783799e-03     2.78876e-13     8.95386e-11
-----------------------------------------------------------------------------------------------------
* Starred lines are suspected outliers and are not included when determining the error.
  A calculation is considered an outlier if it has an uncertainty that lies at an abnormal
  distance from the other uncertainties in this set of calculations.  Outliers are determined
  using the box plot construction with fences. An outlier could indicate a problem with the
  the numerical differentiation or problems with the potential energy, such as discontinuities.

Maximum error obtained for particle = 13, direction = 1:

              |F_model - F_numer|
    error = ----------------------- = 4.62512e-10
              max{|F_numer|, eps}


=====================================================================================================
Grade is based on maximum error across all systems (for a model supporting multiple species):

Maximum error     =     4.62512e-10
Machine precision =     2.22045e-16

Note: Lower grades can reflect errors in the analytical forces, a lack of smoothness in the potential, or loss of precision in the numerical derivative computation.

Grade: A

Comment: The letter grade A was assigned because the normalized error in the computation was 4.62512e-10 compared with a machine precision of 2.22045e-16. The letter grade was based on 'score=log10(error/eps)', with ranges A=[0, 7.5], B=(7.5, 10.0], C=(10.0, 12.5], D=(12.5, 15.0), F>15.0.  'A' is the best grade, and 'F' indicates failure.


=== Verification check vc-forces-numerical-derivative end (2021-06-19 18:31:30) ===
{"usertime":9.85,"memmax":66588,"memavg":0}

  Pair produced Verification Result VC_710586816390_003-and-MO_245095684871_004-1624127481-vr in 9.260463953018188 seconds

openkim@fa2c181e2c6b:~$

In this case, the last line of the output indicates that the job has yielded a verification result named VC_710586816390_003-and-MO_245095684871_004-1624127481-vr. We can navigate to this directory under ~/verification-results/ to see the files it produced.

openkim@fa2c181e2c6b:~$ cd ~/verification-results/
openkim@fa2c181e2c6b:~/verification-results$ ls
VC_710586816390_003-and-MO_245095684871_004-1624127481-vr
openkim@fa2c181e2c6b:~/verification-results$ cd VC_710586816390_003-and-MO_245095684871_004-1624127481-vr/
openkim@fa2c181e2c6b:~/verification-results/VC_710586816390_003-and-MO_245095684871_004-1624127481-vr$ ls
config-Si.xyz  kim.log  kimspec.edn  pipeline.stderr  pipeline.stdin  pipeline.stdout  pipelinespec.edn  report.txt  results.edn

Some of these files, config-Si.xyz and report.txt, are specific to this verification check, while the rest are common to all results. Examining pipeline.stdout and pipeline.stderr, you'll see that they contain the same content that was printed to the terminal when we executed the job. The pipelinespec.edn file contains profiling information for the job. The kim.log file is written out by the KIM API and can be useful in debugging. Finally, the results.edn file is required to be generated by any verification check or test when it runs, and contains a KIM property instance, which in this case specifically corresponds to an instance of the 'verification-check' property definition.


Running a test against a model

Installing and running a test against a model works in the same way as running a verification check against it. Suppose we want to run one of the tests for silicon that uses the LatticeConstantCubicEnergy__TD_475411767977_007 test driver. By convention, all of these tests will begin with the string "LatticeConstantCubicEnergy", so we can use that as a search term to kimitems search. Since we are only interested in tests for silicon, we use the -s flag to specify the species string 'Si':

openkim@fa2c181e2c6b:~$ kimitems search -s Si LatticeConstantCubic
LatticeConstantCubicEnergy_bcc_Si__TE_534114247034_007
LatticeConstantCubicEnergy_diamond_Si__TE_849680434885_007
LatticeConstantCubicEnergy_fcc_Si__TE_828776015817_007
LatticeConstantCubicEnergy_sc_Si__TE_445489171948_007
openkim@fa2c181e2c6b:~$

Supposing we want to compute the lattice constant and cohesive energy of diamond silicon, we can install the corresponding test with

openkim@fa2c181e2c6b:~$ kimitems install LatticeConstantCubicEnergy_diamond_Si__TE_849680434885_007
Notice: Item LatticeConstantCubicEnergy_diamond_Si__TE_849680434885_007 requires a driver (LatticeConstantCubicEnergy__TD_475411767977_007) to work. Would you like to install the driver? [y/n]
y
Downloading LatticeConstantCubicEnergy__TD_475411767977_007...
Installing LatticeConstantCubicEnergy__TD_475411767977_007 to /home/openkim/test-drivers/LatticeConstantCubicEnergy__TD_475411767977_007...
Downloading LatticeConstantCubicEnergy_diamond_Si__TE_849680434885_007...
Installing LatticeConstantCubicEnergy_diamond_Si__TE_849680434885_007 to /home/openkim/tests/LatticeConstantCubicEnergy_diamond_Si__TE_849680434885_007...
Building LatticeConstantCubicEnergy_diamond_Si__TE_849680434885_007...
openkim@fa2c181e2c6b:~$

Similar to the case of the model above, this test uses a test driver and so we are prompted to install it. To run the test against our model, we can again use pipeline-run-pair:

openkim@fa2c181e2c6b:~$ pipeline-run-pair -v LatticeConstantCubicEnergy_diamond_Si__TE_849680434885_007 Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004
+ Running pair (LatticeConstantCubicEnergy_diamond_Si__TE_849680434885_007, Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004)

element:
Si
lattice type:
diamond
modelname:
Tersoff_LAMMPS_Tersoff_1988T2_Si__MO_245095684871_004

Attempting to perform relaxation using initial lattice constant guess of 2.5 Angstroms

Optimization terminated successfully.
         Current function value: -37.043297
         Iterations: 32
         Function evaluations: 66
{'lattice_constant': 5.431230753660202, 'cohesive_energy': 4.630412163496894, 'element': 'Si', 'species': 'Si" "Si" "Si" "Si" "Si" "Si" "Si" "Si', 'crystal_structure': 'diamond', 'space_group': 'Fd-3m', 'wyckoff_code': '8a', 'basis_atoms': '[[0.0 0.0 0.0] [0.25 0.25 0.25] [0.5 0.5 0.0] [0.75 0.75 0.25] [0.5 0.0 0.5] [0.75 0.25 0.75] [0.0 0.5 0.5] [0.25 0.75 0.75]]', 'iterations': 32, 'func_calls': 66, 'warnflag': 0, 'repeat': 0}
{"usertime":1.39,"memmax":64284,"memavg":0}

  Pair produced Test Result TE_849680434885_007-and-MO_245095684781_004-1624129737-tr in 0.6904544830322266 seconds

openkim@fa2c181e2c6b:~$

From the results printed to the terminal, we can see that a lattice constant of 5.4312 Angstroms and a cohesive energy of 4.63 eV were computed by the test (one can verify from the literature that these are indeed by the values predicted by Tersoff's T2 potential). The stdout and stderr, as well as the results.edn file generated by the test can then be found under ~/test-results/TE_849680434885_007-and-MO_245095684781_004-1624129737-tr:

openkim@fa2c181e2c6b:~$ ls test-results/TE_849680434885_007-and-MO_245095684781_004-1624129737-tr/
kim.log  kimspec.edn  pipeline.stderr  pipeline.stdin  pipeline.stdout  pipelinespec.edn  results.edn
openkim@fa2c181e2c6b:~$

Footnotes
  1. You can do kimitems -h to see all of the different subcommands available. Help text for individual subcommands also have their own help text, e.g. kimitems install -h. See README.txt in the home directory for a complete listing of all command line utilities and their help text. 

  2. When using the pipeline-run-* command line utilities, you can tab-complete over the items you have installed inside the container when entering them as arguments. Glob patterns over installed items are also supported.