KIM API V2
|
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 |
ProcessDEDrTerm is a callback function that allows for access to the derivatives of the configuration's partial energy, \(E^{\mathcal{C}}\), with respect to all pair-distances, \(r^{(i,j)}, i,j \in C_{p}\). That is, it allows the model to communicate the values of \(\frac{\partial E^{\mathcal{C}}}{partial r^{(i,j)}}\) to the simulator.
These quantities can be used to compute many quantities of interest associated with the configuration. For example, it is possible to independently compute the partial virial from this information using the formula
\[ \mathbf{V}^{\mathcal{C}} = \sum_{i \in C_p} \mathbf{V}^{\mathcal{C}(i)} = \sum_{i \in C_p} \sum_{j \in \mathcal{N}^{(i)}_{r_{\text{infl}}}} \frac{\bar{E}_i}{\partial \mathbf{r}^{(j)}} \otimes \mathbf{r}^{(j)} = \sum_{i \in C_p} \sum_{j \in \mathcal{N}^{(i)}_{r_{\text{infl}}}} \;\; \sum_{k \not= j; \; k \in \bar{\mathcal{N}}^{(i)}_{r_{\text{infl}}}} \frac{\partial \tilde{E}_i}{\partial r^{(j,k)}} \frac{\partial \bar{r}^{(j,k)}}{\partial \mathbf{r}^{(j)}} \otimes \mathbf{r}^{(j)}. \]
Next Section: Summary of Differences Between kim-api-v1 and kim-api-v2.