/*                                                                            */
/* CDDL HEADER START                                                          */
/*                                                                            */
/* The contents of this file are subject to the terms of the Common           */
/* Development and Distribution License Version 1.0 (the "License").          */
/*                                                                            */
/* You can obtain a copy of the license at                                    */
/* http://www.opensource.org/licenses/CDDL-1.0.  See the License for the      */
/* specific language governing permissions and limitations under the License. */
/*                                                                            */
/* When distributing Covered Code, include this CDDL HEADER in each file and  */
/* include the License file in a prominent location with the name             */
/* LICENSE.CDDL.                                                              */
/* If applicable, add the following below this CDDL HEADER, with the fields   */
/* enclosed by brackets "[]" replaced with your own identifying information:  */
/*                                                                            */
/* Portions Copyright (c) [yyyy] [name of copyright owner].                   */
/* All rights reserved.                                                       */
/*                                                                            */
/* CDDL HEADER END                                                            */
/*                                                                            */

/*                                                                            */
/* Copyright (c) 2017--2019, Regents of the University of Minnesota.          */
/* All rights reserved.                                                       */
/*                                                                            */
/* Contributors:                                                              */
/*    Ryan S. Elliott                                                         */
/*    Ellad B. Tadmor                                                         */
/*    Daniel Karls                                                            */
/*                                                                            */

/*                                                                            */
/* Release: This file is part of the kim-api.git repository.                  */
/*                                                                            */

/**
\page theory Theory for the Portable Model Interface

Previous Section: \ref features.

\anchor energy_per_particle The %KIM API Portable Model Interface (PMI) is
concerned with "simulators" and "portable models" (PMs).  Conceptually, a %KIM
PM is a subprogram that defines an energy-per-particle function, \f$E_i\f$, and
an "influence distance", \f$r_{\text{infl}}\f$, that identifies the particle
separation range over which \f$E_i\f$ 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 PM 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 \f$E_i\f$ for any
configuration containing particles of the supported species.  A %KIM PM 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-PMI-compliant simulator is a computer program that is
compatible with the %KIM API/PMI and 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.  Such a simulator treats a %KIM PM as a black box.  It constructs an
atomistic "Configuration" of interest and passes this configuration to a %KIM
PM 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/PMI is to coordinate the information exchange
between KIM-compliant simulators and %KIM PMs.  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
PMs.  A simulator supporting the %KIM API/PMI can work with all %KIM PMs (as
long as they can agree on units and the necessary species are supported by the
model) and vice versa.

Of central importance to the information exchange process is the definition of
an atomistic "Configuration", \f$\mathcal{C}\f$.  Abstractly, a configuration
consists of a set of particles \f$C_p\f$ and their associated data.  For each
particle \f$i \in C_p\f$, the following additional data must be defined.

  -# The particle's species (H, He, Li, etc.).

  -# The particle's position vector \f$\mathbf{r}^{(i)} = r^{(i)}_j
     \mathbf{e}_j = r^{(i)}_1 \mathbf{e}_1 + r^{(i)}_2 \mathbf{e}_2 + r^{(i)}_3
     \mathbf{e}_3,\f$ where \f$\mathbf{e}_j, \; j=1,2,3\f$ are unit vectors
     along the global fixed Cartesian coordinate system \f$x\f$, \f$y\f$, and
     \f$z\f$ directions, respectively.

  -# The particle's "Contributing Status", which is either "contributing" or
     "non-contributing".  Non-contributing particles exist as part of the
     configuration only to provide the proper environment for the contributing
     particles.  Thus, non-contributing particles (sometimes called "ghost" or
     "padding" particles) can be thought of as providing the appropriate
     boundary conditions for the configuration.

Before proceeding further, we introduce the notation \f$\mathbf{r}^{(i,j)}
\equiv \mathbf{r}^{(j)} - \mathbf{r}^{(i)}\f$ for the relative position vector
from particle \f$i\f$ to particle \f$j\f$, and the notation \f$r^{(i,j)}\f$ for
the magnitude of the vector \f$\mathbf{r}^{(i,j)}\f$.  Note that \f$r^{(j,i)} =
r^{(i,j)}\f$ 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 \f$C_{cp}\f$, and the set of non-contributing
particles \f$C_{ncp}\f$.  So that

\f[
C_{p} = C_{cp} \cup C_{ncp} \quad \text{and} \quad C_{cp} \cap C_{ncp}
= \emptyset.
\f]

For a particle \f$i \in C_p\f$, define the particle's ("punctured") influence
neighborhood, \f$\mathcal{N}^{(i)}_{r_\text{infl}}\f$, as the subset of
particles (not including the particle, itself) in the configuration that are
located no more than \f$r_{\text{infl}}\f$ away from particle \f$i\f$.  That
is,

\f[
\mathcal{N}^{(i)}_{r_\text{infl}} \equiv \{ j \in C_p \;|\;
0 < r^{(i,j)} \le r_{\text{infl}} \}.
\f]

Finally, define the closure of the particle's influence neighborhood,
\f$\bar{\mathcal{N}}^{(i)}_{r_{\text{infl}}}\f$:

\f[
\bar{\mathcal{N}}^{(i)}_{r_{\text{infl}}} \equiv
\mathcal{N}^{(i)}_{r_{\text{infl}}} \cup
\{i\}.
\f]

With the above definitions, it is possible to more specifically identify the
functional dependence for a %KIM PM's energy-per-particle function, \f$E_i\f$:

\f[
E_i = \bar{E}_i(\mathbf{r}^{(j)} \;|\; j \in
\bar{\mathcal{N}}^{(i)}_{r_{\text{infl}}}).
\f]

In fact, due to the principle of material frame indifference, this function must
only be a function of the <em>distances</em> between these particles:

\f[
E_i = \tilde{E}_i( r^{(j,k)} \;|\; j,k \in
\bar{\mathcal{N}}^{(i)}_{r_{\text{infl}}})
.
\f]

Further, it is required that the energy-per-particle function is independent of
the particle numbering.  That is, the value of the energy function cannot
depend on the order in which the particles are labeled with a unique
identification number.

It is usually most convenient to work with the function of position vectors,
\f$\bar{E}_i(\mathbf{r}^{(j)})\f$.  However, in some cases it is advantageous
to work with the function of distances, \f$\tilde{E}_i(r^{(j,k)})\f$.  When the
distinction is unimportant the unaccented notation, \f$E_i\f$, will be
used.

\anchor partial_energy Now a configuration's "Partial Energy" may be defined as
the sum of its contributing particles' energies:

\f[
E^\mathcal{C} = \sum_{i \in C_{cp}} E_i.
\f]

From this definition of the configuration's partial energy, a set of additional
quantities may be derived that are often of interest in simulations.

\anchor partial_particle_energy First, define formally, the configuration's
"Partial Particle Energy" for particle \f$i\f$, \f$E^{\mathcal{C}}_i\f$, as
simply the model's energy-per-particle value for contributing particles and
zero for non-contributing particles,

\f[
E^{\mathcal{C}}_i \equiv
\begin{cases}
E_i, & i \in C_{cp},\\
0,   & i \in C_{ncp}.
\end{cases}
\f]

\anchor partial_forces Second, the configuration's "Partial Force" on particle
\f$j\f$, \f$\mathbf{f}^{\mathcal{C}(j)}\f$, is defined as the negative of the
derivative of the configuration's partial energy with respect to the particle's
position vector:

\f[
\mathbf{f}^{\mathcal{C}(j)} \equiv - \frac{\partial E^{\mathcal{C}}}{\partial
\mathbf{r}^{(j)}}, \quad j \in C_{p}.
\f]

Note that, in general, <em>every</em> particle (both contributing and
non-contributing) has a partial force.

\anchor partial_virial Third, the configuration's "Partial Virial" tensor,
\f$\mathbf{V}^{\mathcal{C}}\f$, is defined in terms of the partial forces:

\f[
\mathbf{V}^{\mathcal{C}} \equiv - \sum_{i \in C_{p}}
\mathbf{f}^{\mathcal{C}(i)} \otimes \mathbf{r}^{(i)}
=
\sum_{i \in C_{p}} \frac{\partial E^{\mathcal{C}}}{\partial \mathbf{r}^{(i)}}
\otimes \mathbf{r}^{(i)},
\f]

where \f$\otimes\f$ is the tensor product operation.

Although the partial virial tensor is given in terms of the absolute particle
positions, \f$\mathbf{r}^{(i)}\f$, it can be shown to be independent of the
coordinate origin.  Indeed,

\f{align*}{
\mathbf{V}^{\mathcal{C}} =
\sum_{i \in C_{p}} \frac{\partial E^{\mathcal{C}}}{\partial \mathbf{r}^{(i)}}
\otimes \mathbf{r}^{(i)}
&=
\frac{1}{2} \left[
\sum_{i \in C_{p}}
\frac{\partial E^{\mathcal{C}}}{\partial \mathbf{r}^{(i)}}
\otimes \mathbf{r}^{(i)}
+
\sum_{j \in C_{p}}
\frac{\partial E^{\mathcal{C}}}{\partial \mathbf{r}^{(j)}}
\otimes \mathbf{r}^{(j)}
\right] \\
&=
\frac{1}{2} \left[
\sum_{i \in C_{p}} \sum_{j \in C_{p}}
\frac{\partial E^{\mathcal{C}}}{\partial r^{(i,j)}}
\frac{\partial r^{(i,j)}}{\partial \mathbf{r}^{(i)}}
\otimes \mathbf{r}^{(i)}
+
\sum_{j \in C_{p}} \sum_{i \in C_{p}}
\frac{\partial E^{\mathcal{C}}}{\partial {r}^{(i,j)}}
\frac{\partial r^{(i,j)}}{\partial \mathbf{r}^{(j)}}
\otimes \mathbf{r}^{(j)}
\right] \\
&=
\frac{1}{2} \left[
\sum_{i \in C_{p}} \sum_{j \in C_{p}}
\frac{\partial E^{\mathcal{C}}}{\partial r^{(i,j)}}
\frac{\mathbf{r}^{(i,j)}}{r^{(i,j)}}
\otimes \mathbf{r}^{(i)}
+
\sum_{j \in C_{p}} \sum_{i \in C_{p}}
\frac{\partial E^{\mathcal{C}}}{\partial {r}^{(i,j)}}
\frac{\mathbf{r}^{(j,i)}}{r^{(i,j)}}
\otimes \mathbf{r}^{(j)}
\right] \\
&=
\frac{1}{2} \left[
\sum_{i \in C_{p}} \sum_{j \in C_{p}}
\frac{\partial E^{\mathcal{C}}}{\partial r^{(i,j)}}
\frac{\mathbf{r}^{(i,j)}}{r^{(i,j)}}
\otimes \mathbf{r}^{(i)}
+
\sum_{j \in C_{p}} \sum_{i \in C_{p}}
\frac{\partial E^{\mathcal{C}}}{\partial {r}^{(i,j)}}
\left(-\frac{\mathbf{r}^{(i,j)}}{r^{(i,j)}}\right)
\otimes \mathbf{r}^{(j)}
\right] \\
&=
\frac{1}{2} \left[
\sum_{i \in C_{p}} \sum_{j \in C_{p}}
\frac{\partial E^{\mathcal{C}}}{\partial r^{(i,j)}}
\frac{\mathbf{r}^{(i,j)}}{r^{(i,j)}}
\otimes \left(\mathbf{r}^{(i)} - \mathbf{r}^{(j)}\right)
\right] \\
&=
\frac{1}{2} \left[
\sum_{i \in C_{p}} \sum_{j \in C_{p}}
\frac{\partial E^{\mathcal{C}}}{\partial r^{(i,j)}}
\frac{\mathbf{r}^{(i,j)}}{r^{(i,j)}}
\otimes \mathbf{r}^{(i,j)}
\right].
\f}

So, an equivalent definition for the virial tensor is

\f[
\mathbf{V}^{\mathcal{C}} \equiv
\sum_{i, j \in C_{p}}
\left(
\frac{1}{2 r^{(i,j)}} \frac{\partial E^{\mathcal{C}}}{\partial r^{(i,j)}}
\right)
\mathbf{r}^{(i,j)} \otimes \mathbf{r}^{(i,j)}.
\f]

\anchor partial_particle_virial It is common to partition the partial virial
into particle contributions, the "Partial Particle Virial" tensors
\f$\mathbf{V}^{\mathcal{C}(i)}\f$ such that

\f[
\mathbf{V}^{\mathcal{C}} = \sum_{i \in C_{p}}
\mathbf{V}^{\mathcal{C}(i)}.
\f]

However, this decomposition is not unique, and different definitions of the
particle virial tensor are found in the literature.  For example, here are two
common definitions:

\f{gather*}{
\mathbf{V}^{\mathcal{C}(i)} \equiv \sum_{j \in C_{p}}
\left(
\frac{1}{2 r^{(i,j)}} \frac{\partial E^{\mathcal{C}}}{\partial r^{(i,j)}}
\right)
\mathbf{r}^{(i,j)} \otimes \mathbf{r}^{(i,j)};
&&
\mathbf{V}^{\mathcal{C}(i)} \equiv \sum_{j, k \in C_{p}}
\left(
\frac{1}{2 r^{(j,k)}}
\frac{\partial E^{\mathcal{C}}_i}{\partial r^{(j,k)}}
\right)
\mathbf{r}^{(j,k)} \otimes \mathbf{r}^{(j,k)}.
\f}

Notice, in the first definition the configuration's partial energy
\f$E^{\mathcal{C}}\f$ is used, whereas in the second definition the partial
particle energy \f$E^{\mathcal{C}}_i\f$ of particle \f$i\f$ is used.  Further,
it is obvious by inspection that with these definitions the sum of partial
particle virial tensors equals the partial virial tensor.

Thus, the %KIM API/PMI does not impose a specific definition for a PM's partial
particle virial tensor.  It simply requires that the PM's definition satisfies
the summation formula \f$\mathbf{V}^{\mathcal{C}} = \sum_{i \in C_{p}}
\mathbf{V}^{\mathcal{C}(i)}\f$.

## Domain Decomposition

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.

\image html  square-lattice-configuration-1.jpg
\image latex square-lattice-configuration-1.pdf

The total energy of the system, particle energy, the total force on each
particle, the total virial tensor, and the particle virial tensors can be
computed using a single configuration.  In this case, the configuration is
\f$\mathcal{T}\f$, the set of particles is \f$T_p\f$, the set of contributing
particles is \f$T_{cp} = T_p\f$, and the set of non-contributing particles is
\f$T_{ncp}=\emptyset\f$.  Then, the total energy is \f$E=E^\mathcal{T}\f$, the
particle energy is \f$E_i=E^{\mathcal{T}}_i\f$, the total force is
\f$\mathbf{f}^{(i)}=\mathbf{f}^{\mathcal{T}(i)}\f$, the total virial tensor is
\f$\mathbf{V} = \mathbf{V}^{\mathcal{T}}\f$, and the particle virial tensor
\f$\mathbf{V}^{(i)} = \mathbf{V}^{\mathcal{T}(i)}\f$.  Next, it is shown how to
compute \f$E\f$, \f$E_i\f$, \f$\mathbf{f}^{(i)}\f$, \f$\mathbf{V}\f$,
and \f$\mathbf{V}^{(i)}\f$
using a decomposition into two domains.

Partition \f$T_p\f$ into two disjoint subsets, \f$A_p\f$ and \f$B_p\f$. That
is, \f$A_p \cap B_p = \emptyset\f$ and \f$A_p \cup B_p = T_p\f$.

\image html square-lattice-configuration-2.jpg
\image latex square-lattice-configuration-2.pdf


Next, define configuration \f$\mathcal{C}\f$ to have particles \f$C_p=T_p\f$
with \f$C_{cp}=A_p\f$ and \f$C_{ncp}=B_p\f$, and configuration
\f$\mathcal{D}\f$ to have particles \f$D_p=T_p\f$ with \f$D_{cp}=B_p\f$ and
\f$D_{ncp}=A_p\f$.  (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.)  Then, we can add up (or "assemble") the
values using the contributions from each domain

\f{align*}{
E &= E^\mathcal{C} + E^\mathcal{D},\\
\mathbf{f}^{(i)} &= \mathbf{f}^{\mathcal{C}(i)} +
\mathbf{f}^{\mathcal{D}(i)},\\
\mathbf{V} &= \mathbf{V}^{\mathcal{C}} +
\mathbf{V}^{\mathcal{D}}, \\
\mathbf{V}^{(i)} &= \mathbf{V}^{\mathcal{C}(i)} +
\mathbf{V}^{\mathcal{D}(i)}.
\f}

Here it becomes clear why the %KIM API/PMI prepends the term "Partial" to all
of its standard quantity names.  In general, the quantities computed by a PM
are only one "partial" contribution to a total.  For example, here we can say
that the force on particle \f$i\f$, \f$\mathbf{f}^{(i)}\f$, is the sum of
\f$\mathcal{C}\f$'s partial force \f$\mathbf{f}^{\mathcal{C}(i)}\f$ and
\f$\mathcal{D}\f$'s partial force \f$\mathbf{f}^{\mathcal{D}(i)}\f$.

For the particle energies, we can just take the value from the (only) domain
where the particle is contributing

\f[
E_i =
\begin{cases}
E^{\mathcal{C}}_i & \text{if $i \in C_{cp}$},\\
E^{\mathcal{D}}_i & \text{if $i \in D_{cp}$}.
\end{cases}
\f]

Next Section: \ref implementation.

*/

LocalWords:  CDDL yyyy Ellad Tadmor Karls kim api infl Ni Cu virial monte Li
LocalWords:  carlo atomistic mathcal mathbf equiv ac cp ncp emptyset le otimes
LocalWords:  unaccented html jpg pdf np ref em PMI PMs PM's
