Hi Josh,
Hello!
I am developing a MS-MEAM model driver for the application and expansion of
MS-MEAM potentials
Would someone please be willing to expound on the what "general periodic
boundary conditions" are, concerning NEIGH-RVEC-F NBC method (mentioned on
lower half of slide 27 of
http://lammps.sandia.gov/workshops/Aug11/Smirichinski/openkim-api-introduction_m3.pdf)
<http://lammps.sandia.gov/workshops/Aug11/Smirichinski/openkim-api-introduction_m3.pdf>
in contrast to the MI-OPBC NBC method.
This reference is for an older versions of the api. The latest version provides this information in the docs/standard.kim file. The current version of the relevant section is:
# In the NEIGH_RVEC methods (NEIGH_RVEC_H and NEIGH_RVEC_F), the Model receives
# the number of particles, coordinates, a half or full neighbor list, and the
# relative position vectors r_ij (r_ij = x_j-x_i). The neighbor list and r_ij
# vectors define the environment of each particle, from which the particles's
# energy is defined. In the case of a half list, a neighbor pair i and j
# (where i < j) with relative position vector (RVEC) r_ij defines two pieces of
# information: (1) j is a neighbor of i with RVEC r_ij and (2) i is a neighbor
# of j with RVEC r_ji = -r_ij. Additionally, the value of the argument
# `numberContributingParticles' indicates that the first
# `numberContributingParticles' contribute their energy to the total and the
# remaining particles do not contribute to the energy (they are "padding"
# particles). When `numberContributingParticles' is equal to `numberParticles'
# the half list is called "symmetric", otherwise it is called "unsymmetric."
# In the case of a full list, any particle that has one or more neighbors
# contributes its energy to the total and those particles with zero neighbors
# do not contribute to the total energy. The Model computes the requested
# quantities using the supplied information. For example, if energy and forces
# are requested, it will compute the total energy of all the particles based on
# their neighbor lists and the derivative of the total energy with respect to
# the positions of the particles. These methods enable the application of
# general periodic boundary conditions, including multiple images. A possible
# future extension to these methods is to allow the Simulator to provide a
# ForceTransformation() function for each neighbor, which would enable the
# application of complex boundary conditions such as torsion and objective
# boundary conditions.
Now, for the types of boundary conditions that can be implemented with the various NBC types.
CLUSTER: this supports only "free" boundary conditions.
MI_OPBC: this supports only orthogonal box periodic boundary conditions. The box side lengths must be at least twice the Model's cutoff range.
NEIGH_PURE: this supports padding particles. With padding particles you can surround the "contributing particles" with any arrangement of padding particles you like. There are many types of boundary conditions that can be implemented with padding particles (e.g., periodic, twist, objective, etc.). In particular, you can implement arbitrary periodic boundary conditions. In this case the Simulator will know the box side lengths and angles. It will then create and place padding particles in the correct locations to represent the periodic images of each particle in the box. As many particle images as are needed can be created as padding particles. Thus, the box can have any size and shape. (The Model has no information about the box and, thus, cannot depend in any way explicitly on the box size and shape.) A down side to NEIGH_PURE is that every padding particle must be "listed". This means the memory must be available to store each padding particle's coordinates, energy, force contributions, etc... This requirement may be removed by using NEIGH_RVEC and its "image" particles feature.
NEIGH_RVEC: this is just like NEIGH_PURE except that the simulator can also create "image" particles. These are designated as images of one of the "listed" particles (contributing and padding particles). In particular, for standard general (arbitrary box size and shape) periodic boundary conditions with N particles in the primitive unit cell, a simulator can use NEIGH_RVEC with only N listed particles. All particles necessary to create the appropriate periodic boundary conditions can be represented as image particles and need not be "listed".
A good way to understand the differences of implementing periodic boundary conditions for each of the MI_OPBC, NEIGH_PURE, and NEIGH_RVEC NBCs, is to look at the ex_test_Ar_FCCcohesive_* set of example openkim_tests that are included with the KIM API package. Each of these tests computes the cohesive energy of an infinite perfect FCC crystal of Ar. The only real difference is how the computation is setup and executed using the various NBC schemes. For MI_OPBC the test sets up a big box (due to the size requirement of the MI_OPBC NBC) with many contributing particles. (In order of most to least memory usage:) For NEIGH_PURE the test sets up a smaller set of particles with only one contributing particle and a larger number of padding particles. For NEIGH_RVEC, the test sets up a single contributing particle and a larger number of image particles.
As a supplement, how does one execute general PBC in a model driver? Does
one use the same lines/if-then condition when NBC = 2 (i.e. for MI-OPBC) or
a different set of commands? If the latter condition is true, can an
example be provided that would establish "general PBC" with NEIGH-RVEC-F?
Such an example does not exist in the examples file in the KIM folders, and
I would like to be able to implement general PBC with my model driver in
LAMMPS (which does not support MI-OPBC).
Generally, a Model (Driver) should be almost completely unconcerned with PBCs. (Only in the MI_OPBC case does it know anything about the PBCs, but this information should only be used to compute the rij vector for neighboring particles. That is, to determine which periodic image of particle j is a neighbor of particle i.)
The Model (Driver) simply needs to correctly interpret the provided neighbor list information based on the NBC method being used. Many of the example models (drivers) provided with the KIM API support all NBC methods. So, you can look there for examples of Models that can correctly compute values for PBC configurations.
In the above described scheme used by the KIM API, most of the difficulty of implementing PBCs (or any other type of boundary conditions) is the responsibility of the Simulator (LAMMPS for your particular interests). The Model simply needs to use, in a correct fashion (according to the KIM API definitions), the neighbor list that the simulator provides. The KIM interface (pair_kim) that has been built into LAMMPS already has the ability to perform PBC computations. So, your MEAM model does not need to know what type of boundary conditions are actually being applied. It just needs to do the 'right thing' with the neighbor list.
This is all quite complicated; I wouldn't expect it to be crystal clear the first time around. So, we can iterate with your questions and I'm confident we'll be able to converge to a shared understanding of the concepts and techniques rather quickly!
Cheers and thanks for contributing!
Ryan