KIM API V2
|
Previous Section: Features of the KIM API package.
At the highest level there are "Simulators" and "Models". Conceptually, a KIM Model is something that defines an energy-per-particle function, \(E_i\), and an "influence distance", \(r_{\text{infl}}\), that identifies the particle separation range over which \(E_i\) depends on the position of its neighboring particles. (Note, this is not necessarily equal to the neighbor list cutoff radius used by a model.) A KIM Model is defined for a specific material system (a specific set of particle species: e.g., Al, Ni, and Cu) and contains all parameter values necessary for evaluating \(E_i\) for any configuration containing particles of the supported species. A KIM Model will, typically, also have the ability to compute other quantities related to the energy-per-particle, such as the force on a particle or the particle's virial.
Conceptually, a KIM Simulator is something that performs a numerical simulation based on the energy, forces, etc. of a set of particles. This could be a molecular dynamics simulation, a monte carlo simulation, or other similar simulation technique. A KIM Simulator treats a KIM Model as a black box. It constructs an atomistic "Configuration" of interest and passes this configuration to a KIM Model along with a list of quantities (energy, force, virial, etc.) to be computed. The model then performs the requested computation and passes the results back to the simulator. Once the simulator has received the model's results it may use these values to advance its simulation and update the atomistic configuration. Typically, this sequence of events is repeated in an iterative process until the simulator determines it has reached convergence or some other stopping condition is achieved.
The purpose of the KIM API is to coordinate the information exchange between KIM Simulators and KIM Models. It does this through the definition of various concepts and quantities, and by providing a set of subroutines that facilitate the necessary communication between simulators and models.
Of central importance to this process is the definition of an atomistic "Configuration", \(\mathcal{C}\). Abstractly, a configuration consists of a set of particles \(C_p\) and their associated data. For each particle \(i \in C_p\), the following additional data must be defined.
Before proceeding further, introduce the notation \(\mathbf{r}^{(i,j)} \equiv \mathbf{r}^{(j)} - \mathbf{r}^{(i)}\) for the relative position vector from particle \(i\) to particle \(j\), and the notation \(r^{(i,j)}\) for the magnitude of the vector \(\mathbf{r}^{(i,j)}\). Note that \(r^{(j,i)} = r^{(i,j)}\) and these are simply two different notations for the same quantity.
Returning to the definition and description of a configuration, a configuration's set of particles may be partitioned into two disjoint sets: The set of contributing particles \(C_{cp}\), and the set of non-contributing particles \(C_{ncp}\). So that
\[ C_{p} = C_{cp} \cup C_{ncp} \quad \text{and} \quad C_{cp} \cap C_{ncp} = \emptyset. \]
For a particle \(i \in C_p\), define the particle's ("punctured") influence neighborhood, \(\mathcal{N}^{(i)}_{r_\text{infl}}\), as the subset of particles (not including the particle, itself) in the configuration that are located no more than \(r_{\text{infl}}\) away from particle \(i\). That is,
\[ \mathcal{N}^{(i)}_{r_\text{infl}} \equiv \{ j \in C_p \;|\; 0 < r^{(i,j)} \le r_{\text{infl}} \}. \]
Finally, define the closure of the particle's influence neighborhood, \(\bar{\mathcal{N}}^{(i)}_{r_{\text{infl}}}\):
\[ \bar{\mathcal{N}}^{(i)}_{r_{\text{infl}}} \equiv \mathcal{N}^{(i)}_{r_{\text{infl}}} \cup \{i\}. \]
With the above definitions, it is possible to more specifically identify the functional dependence for a KIM Model's energy-per-particle function, \(E_i\):
\[ E_i = \bar{E}_i(\mathbf{r}^{(j)} \;|\; j \in \bar{\mathcal{N}}^{(i)}_{r_{\text{infl}}}). \]
In fact, due to the principle of material frame indifference, this function can only be a function of the distances between these particles:
\[ E_i = \tilde{E}_i( r^{(j,k)} \;|\; j,k \in \bar{\mathcal{N}}^{(i)}_{r_{\text{infl}}}) . \]
It is usually most convenient to work with the function of position vectors, \(\bar{E}_i(\mathbf{r}^{(j)})\). However, in some cases it is advantageous to work with the function of distances, \(\tilde{E}_i(r^{(j,k)})\). When the distinction is unimportant the unaccented notation, \(E_i\), will be used.
Now a configuration's "Partial Energy" may be defined as the sum of its contributing particles' energies:
\[ E^\mathcal{C} = \sum_{i \in C_{cp}} E_i. \]
From this definition of the configuration's partial energy, a set of additional quantities may be derived that are often of interest in simulations.
First, define formally, the configuration's "Partial Particle Energy" for particle \(i\), \(E^{\mathcal{C}}_i\), as simply the model's energy-per-particle value for contributing particles and zero for non-contributing particles,
\[ E^{\mathcal{C}}_i \equiv \begin{cases} E_i, & i \in C_{cp},\\ 0, & i \in C_{ncp}. \end{cases} \]
Second, the configuration's "Partial Force" on particle \(j\), \(\mathbf{f}^{\mathcal{C}(j)}\), is defined as the negative of the derivative of the configuration's partial energy with respect to the particle's position vector:
\[ \mathbf{f}^{\mathcal{C}(j)} \equiv - \frac{\partial E^{\mathcal{C}}}{\partial \mathbf{r}^{(j)}}, \quad j \in C_{p}. \]
Note that, in general, every particle (both contributing and non-contributing) has a partial force. As a special case, consider a configuration, \(\mathcal{C}^i\), equivalent to \(\mathcal{C}\) except that only particle \(i\) is contributing. In this case, the partial forces are
\[ \mathbf{f}^{\mathcal{C}^i(j)} = \begin{cases} -\frac{\partial \bar{E}_i}{\partial \mathbf{r}^{(j)}} & j \in \mathcal{N}^{(i)}_{r_{\text{infl}}}, \\ 0, & \text{otherwise}. \end{cases} \]
This can be thought of as the force on particle \(j\) due to particle \(i\). With this notation, it is possible to obtain the identity
\[ \mathbf{f}^{\mathcal{C}(j)} = \sum_{i \in C_{cp}} \mathbf{f}^{\mathcal{C}^i(j)}. \]
Third, the configuration's "Partial Particle Virial" tensor for contributing particle \(i \in C_{cp}\), \(\mathbf{V}^{\mathcal{C}(i)}\), is defined in terms of the derivative of its per-particle-energy function:
\[ \mathbf{V}^{\mathcal{C}(i)} \equiv \sum_{j \in \mathcal{N}^{(i)}_{r_{\text{infl}}}} \frac{\partial \bar{E}_i}{\partial \mathbf{r}^{(j)}} \otimes \mathbf{r}^{(j)} = \sum_{j \in \mathcal{N}^{(i)}_{r_{\text{infl}}}} -\mathbf{f}^{\mathcal{C}^i(j)} \otimes \mathbf{r}^{(j)} = -\sum_{j \in \mathcal{N}^{(i)}_{r_{\text{infl}}}} \mathbf{f}^{\mathcal{C}^i(j)} \otimes \mathbf{r}^{(j)} . \]
The partial particle virial is zero for non-contributing particles. That is, \(\mathbf{V}^{\mathcal{C}(i)} = \mathbf{0}\) for \(i \in C_{ncp}\).
Fourth and finally, the configuration's "Partial Virial" tensor, \(\mathbf{V}^{\mathcal{C}}\), is the sum of its partial particle virial tensors:
\[ \mathbf{V}^{\mathcal{C}} \equiv \sum_{i \in C_{p}} \mathbf{V}^{\mathcal{C}(i)}. \]
Note that an equivalent expression for the partial virial tensor is given by
\[ \mathbf{V}^{\mathcal{C}} = - \sum_{i \in C_{p}} \mathbf{f}^{\mathcal{C}(i)} \otimes \mathbf{r}^{(i)}. \]
The definitions of a configuration's partial energy, forces, and virial are designed to allow for easy (and low communication) parallel computation via domain decomposition. This section presents a simple example that illustrates how this works.
Start with a configuration of particles corresponding to a finite strip of a centered square lattice.
The total energy of the system and the total force on each particle can be computed using a single configuration. In this case, the configuration is \(\mathcal{T}\), the set of particles is \(T_p\), the set of contributing particles is \(T_{cp} = T_p\), and the set of non-contributing particles is \(T_{ncp}=\emptyset\). Then, the total energy is \(E=E^\mathcal{T}\), and the total force on particle \(i \in T_p\) is \(\mathbf{f}^{(i)}=\mathbf{f}^{\mathcal{T}(i)}\). Next, it is shown how to compute \(E\) and \(\mathbf{f}^{(i)}\) using a two-domain decomposition.
Partition \(T_p\) into two disjoint subsets, \(A_p\) and \(B_p\). That is, \(A_p \cap B_p = \emptyset\) and \(A_p \cup B_p = T_p\).
Next, define configuration \(\mathcal{C}\) to have particles \(C_p=T_p\) with \(C_{cp}=A_p\) and \(C_{ncp}=B_p\), and configuration \(\mathcal{D}\) to have particles \(D_p=T_p\) with \(D_{cp}=B_p\) and \(D_{ncp}=A_p\). Then,
\[ E = E^\mathcal{C} + E^\mathcal{D}, \]
and
\[ \mathbf{f}^{(i)} = \mathbf{f}^{\mathcal{C}(i)} + \mathbf{f}^{\mathcal{D}(i)}. \]
In practice, one can get away with including only those non-contributing particles that fall within the "influence distance" of at least one contributing particle.
Next Section: Implementation.