Welcome to kim-tools's documentation!
Note
kim-tools 0.3 requires AFLOW 4.0.5 or greater. See Standalone Installation if you are using or developing Test Drivers outside the KIM Developer Platform
image source: http://textfiles.com/underconstruction/
Contents:
Introduction
This package is designed to facilitate writing OpenKIM Test Drivers in the Crystal Genome (XtalG) framework for arbitrary crystals. Fundamentally, a KIM Test Driver is an arbitrary executable named runner that takes custom inputs from stdin using custom and standard Jinja2 templating, and writes a file named output/results.edn containing one or more KIM Property Instances. This minimal specification is all the KIM Processing Pipeline needs to run KIM Tests and allows a great amount of flexibility for developers. However, the open-endedness makes creation of new Test Drivers difficult to tutorialize, and the resulting Test Drivers have a non-uniform input syntax, making them cumbersome to use outside of the KIM Pipeline.
Crystal Genome (XtalG) is the OpenKIM thrust for generalizing our testing framework to apply to arbitrary crystals. It uses AFLOW Prototype Labels (see figure below) to describe arbitrary crystal structures in a complete, concise, and human-readable manner. A thorough description of the AFLOW prototype label can be found here: https://aflow.org/prototype-encyclopedia/Tutorials/AFLOW_Prototype_Label/. Because it is unreasonable for every OpenKIM test developer to learn the crystallography required to write XtalG tests from scratch, common input, output, and analysis tasks must be easy to use automatically.
The AFLOW prototype label. In short, it is a string providing the stoichiometry, Pearson symbol, space group, and Wyckoff positions of an arbitrary crystal. Image source and more info: https://arxiv.org/pdf/2401.06875.
This package addresses these issues by providing a base class SingleCrystalTestDriver (itself inheriting from a yet more general class KIMTestDriver) that automates many of the common programming tasks needed to write an OpenKIM Test Driver for XtalG. Additionally, due to the common interface, Test Drivers written using this base class are easier to invoke outside of the OpenKIM infrastructure, and can work with arbitrary ASE Atoms objects. If a Test Driver uses only ASE for computations, it can even work with arbitrary ASE Calculator objects. In the future, all ASE-only Test Drivers written using kim_tools will be incorporated into the kimvv package to be distributed for users to test their own models.
Contact us at https://openkim.org/contact/ with any comments or questions.
Test Driver Creation Tutorial
If you wish to use this package to develop an OpenKIM Test Driver, after setting up a suitable development environment (detailed on the rest of this page), follow the Test Driver Creation Tutorial.
KIM Developer Platform
The KIM Developer Platform (KDP) is a Docker image providing an emulation of the KIM Processing Pipeline. It is the recommended environment for developing OpenKIM content, and is required to fully test integration of Test Drivers into the pipeline before they are submitted to openkim.org. kim-tools and all requirements are included in KDP version 1.4.0 and higher. The KDP is also able to run using Singularity/Apptainer or Podman, making it compatib. For more info on running using Singularity, see here.
Standalone Installation
For standalone usage of kim-tools outside of the KDP, some requirements must be satisfied first.
Prerequisites
Before installing the package using pip, you will need to install AFLOW 4.0.5 or greater. The KIM API is required to run any Test Drivers that use LAMMPS, or to use KIM Models with ASE-only Test Drivers (recommeded). GNU Units is also required. You may have to do some configuration for your specific machine for things like Conda installation directories, pip installation directories, etc.
AFLOW
The installation script for kim-tools will check that the aflow executable is in your PATH and is version 4.0.5 or greater. At the time of writing, AFLOW 4 is in prerelease
at https://github.com/aflow-org/aflow, so the installation options may change, but the following options appear to work well so far:
Ubuntu precompiled binary
Ubuntu
.debpackageHomebrew
Build from source using the
release_vcpkgpreset (read their README carefully for requirements)
Installing AFLOW using snap does NOT work, as it does not have access to the files saved by the Python tempfile library (e.g. /tmp), at least using default settings.
KIM API and kimpy
Installation instructions for the KIM API can be found here, and for kimpy here. Recommended installation methods are building from source or installing from conda-forge (installing the kimpy package will automatically install kim-api as well). If you need LAMMPS as well (because you are running or developing Test Drivers that use it, or you wish to use LAMMPS Simulator Models), a good option is to install the lammps package from conda-forge as well.
GNU Units
kim-tools uses the GNU Units utility for automatic unit conversion. You can check if you already have it by running units --help or gunits --help. It is available from many native package managers such as apt and homebrew (as gnu-units). If you are on a system where you do not have admin access, you may have to build it from source. Once you download the source code from the GNU website, you should be able to install it by running the following commands from the source directory. The --prefix=/desired/install/dir option specifies the install location, and you will have to add /desired/install/dir/bin to your PATH. For more info, see the INSTALL and README files in the source.
./configure --prefix=/desired/install/dir && make && make install
Installation
Once the above prerequisites are satisfied, you can install using pip:
pip install kim-tools