Features of the KIM API package

Previous Section: Table of Contents.

This version of the KIM API package is distributed under the CDDL 1.0 Open Source License.

The current version of the KIM API package supports the following features:

• Programming Languages: Currently supported programming languages include C, C++, Fortran.
• Best Practice API Design: The guiding design principle for the KIM API has been simplicity. In addition to this, general API design best practices have been used. These include: implementation hiding (pimpl idiom), loose coupling, minimal-completeness, ease of use (discoverable, difficult to misuse, consistent, orthogonal), static factory methods, use of namespaces, const-correctness, and avoiding the use of abbreviations.
• Language Idiom Support: Wherever it makes sense and is possible the KIM API supports common idioms of the native language. For example, all C API routines that return an error status do so using the C function return value. For Fortran, all such API routines are SUBROUTINES and have their final argument as an error status.
• Extensible, Strongly-Typed Enumerations: The KIM API implements a set of typed constants for each category of entity that it defines (KIM::ChargeUnit, KIM::ComputeArgumentName, KIM::ComputeCallbackName, KIM::DataType, KIM::EnergyUnit, KIM::LanguageName, KIM::LengthUnit, KIM::LogVerbosity, KIM::ModelRoutineName, KIM::Numbering, KIM::SpeciesName, KIM::SupportStatus, KIM::TemperatureUnit, KIM::TimeUnit). This allows for backward-compatible additions to the enumerations in future versions of the KIM API. Further, the strong-typing greatly facilitates debugging.
• Numbering Origin Support: Support for automatic translation between zero-based numbering of particles (C-style numbering beginning with zero) and one-based numbering (Fortran-style numbering beginning with one).
• Data Communication: Communication of an arbitrary number of arguments and callback routines between a model (interatomic potential) and a simulator (simulation code that uses a model).

• Data types: integer and double.

  Each of the data types can be used to create multi-dimensional array arguments that are exchanged between models and simulators. The KIM API standard defines the dimension and extent of these arrays for each argument. However, this information is not discoverable at run-time. Thus, it is left to the programmer to ensure that the correct values are used.

  Currently, the KIM API does not define any (more complex) data structures. However, in the future (as the need arises, and in consultation with the atomistic and molecular simulation community) additional data types and data structures may be introduced.

• Physical Units: The KIM API standard defines the physical units for each argument exchanged between a model and simulator. A simulator provides a set of requested units to define a unit system and a model either accepts this unit system (and performs appropriate unit conversions for its parameters), or it rejects the request and reports the unit system to be used.
• Neighbor lists: Neighbor list routines are expected to be provided by the calling simulator. All neighbor lists are full, unsorted lists that must contain all particles within the specified cutoff distance (but may contain additional particles). A model must request one or more neighbor lists, each with an associated cutoff distance. (Cutoff distances are typically distinct, but may repeat. Repeated cutoff distances allow a model to simultaneously access the neighbors of multiple particles without needing to make copies of the neighbor list(s).) A simulator must provide all such requested lists and ensure that these lists contain only a small number of particles that are located outside the cutoff distance. Models must provide "hints" about how they use neighbor lists. These hints allow the simulator to, optionally, optimize its neighbor list build algorithm.
• Particle Species: The KIM API provides the ability to designate the physical species of each particle in a simulation. Currently, only one identifier is provided for each element in the periodic table. In the future support for models that require multiple types of each element may be added.
• Model Parameters: The KIM philosophy views a model as a well-defined computational code that includes specific values for all parameters needed to perform an actual computation. However, it is often useful to explore how a model's predictions vary as the values of its parameters are varied. For this reason, the KIM API allows a model to (optionally) "publish" its parameters so that a simulator may modify them during the course of a simulation.
• Model Drivers: The KIM API package provides the ability to create model driver routines. A model driver is an implementation of an interatomic potential functional-form. A model for a given material can be created which uses an existing model driver by providing a file or files with the appropriate parameter values for the material system of interest.
• Logging capabilities: The KIM API package provides a full-featured logging capability that facilitates the identification and debugging of errors. In addition to built-in support for logging within model codes, the KIM API also provides access to logging capabilities for general use by simulator codes.
• Caching capabilities:The KIM API package provides a mechanism to store a pointer to a memory (cache) buffer in the main API objects (KIM::Model and KIM::ComputeArguments). In each case there is a "ModelBufferPointer" which is for use by the model's routines and a "SimulatorBufferPointer" which is for use by the simulator. (These buffer pointers are not to be used for communication between the simulator and model, and therefore the ModelBufferPointer is not accessible to the simulator and vise-versa.)
• Semantic Versioning: The KIM API package conforms to the Semantic Versioning 2.0.0 standard. This standard is useful because its version numbers and the way they change convey meaning about the underlying code and what has been modified from one version to the next. In addition, the KIM API provides basic tools for comparing and parsing Semantic Version strings.

Next Section: Theory.