KIM API V2
Implementation

Previous Section: Theory.

In code, a model (or model driver) consists of six routines which perform specific tasks. The first is the ModelCreate (or ModelDriverCreate) routine, which performs initialization tasks for the model object. The second is the ModelComputeArgumentsCreate routine, which performs initialization tasks for a compute-arguments object. The third is the ModelComputeArgumentsDestroy routine, which performs finalization tasks for a compute-arguments object. The fourth is the ModelCompute routine, which uses the configuration information stored in a compute-arguments object to perform the model's core computational tasks. The fifth is the ModelRefresh routine, which performs updates after a simulator makes changes to the model's parameters (if this is supported). The sixth is the ModelDestroy routine, which performs finalization tasks for the model object.

To interact with a model, a simulator creates a model object (which, in part, includes execution of the model's ModelCreate routine). Using this object, the simulator creates a compute-arguments object (which, in part, includes execution of the model's ModelComputeArgumentsCreate routine). Then, the simulator provides a compute-arguments object to the model's ModelCompute function. There are input compute-arguments that include the various components that make up a configuration (number of particles, particle position vectors, etc.). And, there are output compute-arguments that include the quantities (like partial energy and partial forces), defined in Section Theory, associated with the configuration. There are also compute-callback functions (such as a function to get a particle's neighbor list) that the simulator provides for use by the model.

The KIM API provides a list of all compute-arguments and compute-callbacks defined as part of the official API. Each such argument and callback has a "Support Status" which 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.

Next, lists of each input compute-argument, output compute-argument, and compute-callback are provided. To be explicit, below 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}}_{32}, V^{\mathcal{C}}_{13}\) 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.