This directory has an application that models grain growth in the
presence of strain.

The grain growth is simulated by a Potts model in the kinetic Monte
Carlo code SPPARKS -- https://spparks.github.io

Clusters of like spins on a lattice represent grains.  The Hamiltonian
for the energy due of a collection of spins includes a strain term and
is described on this page in the SPPARKS documentation:

https://spparks.github.io/doc/app_potts_strain.html

The strain is computed by the LAMMPS molecular dynamics code --
https://www.lammps.org -- as a particle displacement where pairs of
atoms across a grain boundary are of different types and thus push off
from each other due to a Lennard-Jones sigma between particles of
different types that is larger than the sigma between particles of the
same type (interior to grains).

lmpspk.cpp          main program
                    it links to LAMMPS and SPPARKS as libraries
in.spparks          SPPARKS input script, without the run command
lmppath.h           contains path to LAMMPS home directory
spkpath.h           contains path to SPPARKS home directory

-----------------------------------

(1) To build and run this coupled application, you must have SPPARKS
built on your system.  It's WWW site is https://spparks.github.io and
it can be downloaded as a tarball or cloned as a local Git repo.

To build SPPARKS, do the following:

% cd spparks/src
% make mpi
% make mode=lib mpi      # build SPPARKS as a library

-----------------------------------

(2) You must also build the coupling library in
lammps/examples/COUPLE/library.

To build the coupling library, do the following:

% cd lammps/examples/COUPLE/library
% make -f Makefile.mpi

-----------------------------------

(3) Edit the Makefile.mpi, lmppath.h, and spkpath.h files in this
directory to make them suitable for your box.  Each of the 3 files
has a comment telling you what to do.

-----------------------------------

(4) Build the coupled lmpspk application in this directory.

% make -f Makefile.mpi

This should give you a lmpspk executable.

-----------------------------------

(5) Run the test simulation

You can run lmpspk in serial or parallel as:

% lmpspk Niter Ndelta Sfactor in.spparks
% mpirun -np 4 lmpspk Niter Ndelta Sfactor in.spparks

where

Niter = # of outer iterations
Ndelta = time to run MC in each iteration
Sfactor = multiplier on strain effect
in.spparks = SPPARKS input script

The log files included in this directory are for this run:

% lmpspk 20 10.0 1 in.spparks

This application is an example of a coupling where the driver code
(lmpspk) alternates back and forth between the 2 applications (LAMMPS
and SPPARKS).  Each outer timestep in the driver code, the following
tasks are performed.  One code (SPPARKS) is invoked for a few Monte
Carlo steps.  Some of its output (spin state) is passed to the other
code (LAMMPS) as input (atom type).  The the other code (LAMMPS) is
invoked for a few timesteps.  Some of its output (atom coords) is
massaged to become an input (per-atom strain) for the original code
(SPPARKS).

The driver code launches both SPPARKS and LAMMPS in parallel and they
both decompose their spatial domains in the same manner.  The datums
in SPPARKS (lattice sites) are the same as the datums in LAMMPS
(coarse-grained particles).  If this were not the case, more
sophisticated inter-code communication could be performed.  Note that
the in.lammps and data.lammps files are not inputs; they are generated
by the lmpspk driver.

You can look at the log files in the directory to see LAMMPS and
SPPARKS output for this simulation run on 1 and 4 processors.  Dump
files produced by the run are named dump.mc and dump.md.  The image
PPM files show snapshots from the SPPARKS and LAMMPS output.  Compare
the image_spparks.0019.ppm and image_lammps.0190.ppm file.  They were
written at the same point in the simulation by both codes.  The color
maps for the 2 codes are not the same, but the morphology of the
grains is.
