KIM API V2
Implementation

Previous Section: Theory.

In code, a model (or model driver) consists of four routines which perform specific tasks. The first is the ModelCreate (or ModelDriverCreate) routine, which performs all necessary initialization tasks. The second is the ModelCompute routine, which performs the core computational tasks. The third is the ModelRefresh routine, which performs any necessary updates after a simulator makes changes to the model's parameters (if this is supported). The fourth is the ModelDestroy routine, which performs all necessary finalization tasks.

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 provides a set of "Arguments" to the model's ModelCompute function. There are input arguments that include the various components that make up a configuration (number of particles, particle position vectors, etc.). And, there are output arguments that include the quantities (like partial energy and partial forces), defined in Section Theory, associated with the configuration. There are also "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 arguments and callbacks defined as part of the official API. Each 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 for every argument defined by the KIM API. It is the responsibility of the simulator to use the model object interface to determine the support status of each argument and to use this information to determine if the model is capable of performing the desired computation.

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

Input argument table:

Argument Name Unit Data Type Extent Memory Layout Valid Support Statuses (bold – default)
numberOfParticles N/A double 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 argument table:

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

Callback table:

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.