Sketch of our current thoughts for kim-api-v2:
* A model is something that provides a particular energy-per-particle
function, E_i, and a "modelEnergyInfluenceDistance" value that identifies the
influence distance over which a particle's energy function, E_i, depends on
the positions of its neighboring particles. (Note, this is not necessarily
equal to the (neighbor list) "cutoff" radius used by a model.)
* A configuration, C, is a set of particles (Cp), their species, status,
coordinates, etc. as described below. The set of contributing particles is
Cc \subset Cp and the set of non-contributing particles is Cnc = Cp\Cc.
* A configuration's energy is defined as the sum of its contributing particles'
energies: E^C = \sum_{i \in Cc} E_i.
* A configuration's partialForce on particle i (in Cp), f^C_i, is defined as the
negative of the derivative of the configuration's energy with respect to the
coordinates, x_i, of particle i: f^C_i = -\frac{\partial E^C}{\partial x_i}.
Note, that generally both contributing and non-contributing particles have
non-zero partialForces.
These definitions for E^C and F^C_i are useful for domain-decomposition (as
well as other situations: periodic BC's, etc.). As an example, consider a
total energy and total force computation on an isolated block of 100
particles. Let this set of particles be denoted by Tp. We can compute the
total energy of the system and the total force on each particle using a
single configuration. In this case, the configuration is T, the set of
particles is Tp, the set of contributing particles is Tc=Tp, and the set of
non-contributing particles is Tnp=\emptyset. Then, the total energy is
E=E^T, and the total force on particle i \in Tp is f_i=f^T_i. Next, let's
consider how we can compute E and f_i using a two-domain decomposition.
Partition Tp into two disjoint subsets, Ap and Bp. That is, Ap \cap Bp =
\emptyset and Ap \cup Bp = Tp. Then define configuration C to have particles
Cp=Tp with Cc=Ap and Cnp=Bp, and configuration D to have particles Dp=Tp with
Dc=Bp and Dnp=Ap. Then, E = E^C + E^D, and f_i = f^C_i + f^D_i. In
practice, one can get away with including only those non-contributing
particles that fall within the "modelEnergyDomainRadius" of at least one
contributing particle.
* Unified configuration description: A configuration consists of the following
quantities (all are required):
+ numberOfParticles
(int scalar) The number of particles (contributing and non-contributing)
in the configuration.
+ numberOfSpecies
(int scalar) The number of distinct particle species in the
configuration. (Note that this may be different than the number of
species supported by the model or simulator; e.g., the simulator may
support multiple species but the specific configuration contains only
one species.)
+ particleSpecies[numberOfParticles]
(int array) The species id (as defined by the model) of each particle.
+ particleStatus[numberOfParticles]
(int array) 0/1 status of each particle in the configuration:
"non-contributing" (0) or "contributing" (1).
+ coordinates[numberOfParticles,3]
(double array) Cartesian coordinates of each particle.
* Required random-access, unordered full neighbor list with multiple cutoff
values. The Simulator is required to provide a set of neighbor lists that
are fully consistent with the configuration description described above. (In
particular, the Model must---in principle---be able to independently
construct its own *equivalent* neighbor list using just the configuration
information described above.) The Model will specify some number of cutoff
values. Each neighbor list must contain at least all particles within the
corresponding cutoff distance (but may contain particles outside the cutoff
distance).
* the "index" values (as in KIM_API_get_index()) will be eliminated, the
argument names (e.g., "coordinates") will be used exclusively.
* FIXED parameters will be eliminated. Only changeable "FREE" parameters will
be "published". (Fixed parameters will now need to be stored in the Model
Buffer, and will be unaccessible to the Simulator.)
* Remove KIM_API_allocate() from api in order to make memory management scheme
less confusing; Provide a set of memory management helper subroutines in a
separate package.
* Numerous other syntactic and styistic improvements.