kim-api  2.0.2+v2.0.2.GNU
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).

Previous Section: Theory.

In code, a model (or model driver) consists of up to eight routines which perform specific tasks:

  1. The ModelCreate (or ModelDriverCreate ) routine (required), which performs initialization tasks for the model object.
  2. The ModelComputeArgumentsCreate routine (required), which performs initialization tasks for a compute-arguments object.
  3. The ModelCompute routine (required), which uses the configuration information stored in a compute-arguments object to perform the model's core computational tasks.
  4. The ModelExtension routine (optional), which provides a mechanism for creating and using non-standard extensions to the KIM API.
  5. The ModelRefresh routine (required if parameter pointers are set, otherwise should not be provided), which performs updates after a simulator makes changes to the model's parameters (if this is supported).
  6. The ModelWriteParameterizedModel (optional) routine, which can be used to write the parameter files and CMake file necessary to create a new parameterized model from the current set of in-memory parameters.
  7. The ModelComputeArgumentsDestroy routine (required), which performs finalization tasks for a compute-arguments object.
  8. The ModelDestroy routine (required), which performs finalization tasks for the model object.

These are summarized in the following table.

Model Routine Required / Optional
KIM::MODEL_ROUTINE_NAME::Create required
KIM::MODEL_ROUTINE_NAME::ComputeArgumentsCreate required
KIM::MODEL_ROUTINE_NAME::Compute required
KIM::MODEL_ROUTINE_NAME::Extension optional
KIM::MODEL_ROUTINE_NAME::Refresh required if one or more parameter pointers set, otherwise should not be provided
KIM::MODEL_ROUTINE_NAME::WriteParameterizedModel optional
KIM::MODEL_ROUTINE_NAME::ComputeArgumentsDestroy required
KIM::MODEL_ROUTINE_NAME::Destroy required

The above table indicates which routines must be provided by a model. For optional routines, each model must indicate that the routine is required or optional for use by the simulator, as described below.

The interaction between the simulator and a model involves the following steps:

The KIM API provides a list of all compute-arguments and compute-callbacks defined as part of the official API. Each argument and callback has a "Support Status" that can be one of four values: requiredByAPI, notSupported, required, or optional. A model specifies a support status value, as part of its ModelComputeArgumentsCreate routine, for every compute-argument and compute-callback defined by the KIM API. It is the responsibility of the simulator to use the compute-arguments object interface to determine the support status of each compute-argument and compute-callback and to use this information to determine if the model is capable of performing the desired computation.

Below, lists of each input compute-argument, output compute-argument, and compute-callback are provided. To be explicit, zero-based particle numbering is used where necessary.

Input compute-argument table:

Compute Argument Name Unit Data Type Extent Memory Layout Valid Support Statuses (bold – default)
numberOfParticles N/A integer 1 requiredByAPI
particleSpeciesCodes N/A integer numberOfParticles \(sc^{(0)}, sc^{(1)}, \dots\) requiredByAPI
particleContributing N/A integer numberOfParticles \(c^{(0)}, c^{(1)}, \dots\) requiredByAPI
coordinates length double numberOfParticles * 3 \(r^{(0)}_1, r^{(0)}_2, r^{(0)}_3, r^{(1)}_1, r^{(1)}_2, \dots\) requiredByAPI

Output compute-argument table:

Compute Argument Name Unit Data Type Extent Memory Layout Valid Support Statuses (bold – default)
partialEnergy energy double 1 required, optional, notSupported
partialForces force double numberOfParticles * 3 \(f^{\mathcal{C}(0)}_1, f^{\mathcal{C}(0)}_2, f^{\mathcal{C}(0)}_3, f^{\mathcal{C}(1)}_1, f^{\mathcal{C}(1)}_2\dots\) required, optional, notSupported
partialParticleEnergy energy double numberOfParticles \(E^{\mathcal{C}}_0, E^{\mathcal{C}}_1, E^{\mathcal{C}}_2, \dots\) required, optional, notSupported
partialVirial energy double 6 \(V^{\mathcal{C}}_{11}, V^{\mathcal{C}}_{22}, V^{\mathcal{C}}_{33}, V^{\mathcal{C}}_{23}, V^{\mathcal{C}}_{31}, V^{\mathcal{C}}_{12}\) required, optional, notSupported
partialParticleVirial energy double numberOfParticles * 6 \(\mathbf{V}^{\mathcal{C}(0)}, \mathbf{V}^{\mathcal{C}(1)}, \mathbf{V}^{\mathcal{C}(2)}, \dots\) required, optional, notSupported

Compute-callback table:

Compute Callback Name Valid Support Statuses (bold – default)
GetNeighborList requiredByAPI
ProcessDEDrTerm required, optional, notSupported
ProcessD2EDr2Term required, optional, notSupported

Next Section: Summary of Differences Between kim-api-v1 and kim-api-v2.