/*                                                                            */
/* 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-2.0.2 package.                   */
/*                                                                            */

/**
\page theory Theory

Previous Section: \ref features.

\anchor energy_per_particle The %KIM API is concerned with "simulators" and
"models".  Conceptually, a %KIM Model 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 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 \f$E_i\f$ 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-compliant simulator is a computer program that is
compatible with the %KIM API 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 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-compliant 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.  A
simulator supporting the %KIM API can work with all %KIM Models (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 Model'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 can
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]

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 does not impose a specific definition for a model's partial
particle virial tensor.  It simply requires that the model'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 prepends the term "Partial" to all of
its standard quantity names.  In general, the quantities computed by a model
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
