"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

pair_style kim command :h3

[Syntax:]

pair_style kim model :pre

model = name of KIM model (potential)

[Examples:]

pair_style kim model_Ar_P_Morse
pair_coeff * * Ar Ar :pre

[Description:]

This pair style is a wrapper on the "Knowledge Base for Interatomic
Models (KIM)"_http://openkim.org, repository of interatomic
potentials, so that they can be used by LAMMPS scripts.

In KIM lingo, a potential is a "model" and a model contains both the
analytic formulas that define the potential as well as the parameters
needed to run it for one or more materials, including coefficients and
cutoffs.

The argument {model} is the name of the model for a specific potential
as KIM defines it.  In principle, LAMMPS can invoke any KIM model.
You should get an error message from either LAMMPS or KIM if there is
an incompatibility.

Only a single pair_coeff command is used with the {kim} style which
specifies the mapping of LAMMPS atom types to KIM elements.  This is
done by specifying N additional arguments after the "* *" in the
pair_coeff command, where N is the number of LAMMPS atom types:

N element names = mapping of KIM elements to atom types :ul

As an example, imagine the KIM model supports Si and C atoms.  If your
LAMMPS simulation has 4 atoms types and you want the 1st 3 to be Si,
and the 4th to be C, you would use the following pair_coeff command:

pair_coeff * * Si Si Si C :pre

The 1st 2 arguments must be * * so as to span all LAMMPS atom types.
The first three Si arguments map LAMMPS atom types 1,2,3 to Si as
defined within KIM.  The final C argument maps LAMMPS atom type 4 to C
as defined within KIM.  If a mapping value is specified as NULL, the
mapping is not performed.  This can be used when a {kim} potential is
used as part of the {hybrid} pair style.  The NULL values are
placeholders for atom types that will be used with other potentials.

:line

In addition to the usual LAMMPS error messages, the KIM library itself
may generate errors, which should be printed to the screen.  In this
case it is also useful to check the kim.log file for additional error
information.  This file kim.log should be generated in the same
directory where LAMMPS is running.

:line

Here is information on how to build KIM for use with LAMMPS.  There is
a directory lib/kim with an important file in it: Makefile.lammps.
When you build LAMMPS with its KIM package installed (which contains
the pair_style kim command), then it will use the settings in
lib/kim/Makefile.lammps to find KIM header files and the KIM library
itself for linking purposes.  Thus you should insure Makefile.lammps
has the correct settings for your system and your build of KIM.

Consult the KIM documentation for further details on KIM specifics.

OpenKIM is available for download from "this site"_http://openkim.org,
namely http://openkim.org.  The tarball you download is
"openkim-api-vX.X.X.tgz", which can be unpacked via

tar xvfz openkim*tgz :pre

The openkim/DOCs directory has further documentation.  For more
information on installing KIM and troubleshooting refer to
openkim/INSTALL.

Here is a brief summary of how to build KIM:

Set the following environment variables.  It is recommended to place
the above environment variables definitions in your shell setup file
which is located in your home directory (e.g. ~/.bashrc). :olb,l

   (a) Define the location of the openKIM API root directory.  For example, 
       if you untarred the `openkim-api-vX.X.X.tgz' tarball in your home 
       directory, you would do: :pre

       bash:
       % export KIM_DIR=~/openkim-api-vX.X.X/ :pre

       tcsh:
       % setenv KIM_DIR ~/openkim-api-vX.X.X/ :pre

       Make sure to include the trailing slash. The `%' symbol represents the
       bash sell prompt and should not be typed. :pre

   (b) By default, all makefiles use the GNU compilers for 64 bit Linux.  
       In order to use the Intel compiler, define the environment variable
       KIM_INTEL :pre

       bash: 
       % export KIM_INTEL="yes" :pre

       tcsh:
       % setenv KIM_INTEL "yes" :pre

   (c) For a 32 bit machine, define the environment variable KIM_SYSTEM32 :pre

       bash: 
       % export KIM_SYSTEM32="yes" :pre

       tchs:
       % setenv KIM_SYSTEM32 "yes" :pre

   (d) Define variable for dynamic linking (preferable option) :pre
      
       bash:
       export KIM_DYNAMIC=yes :pre

       tcsh:
       setenv KIM_DYNAMIC=yes :pre

       If this environment variable is not set the default will be
       static linking.  In that case all KIM models will be linked,
       producing potentially a very large file.  It is also possible
       to build KIM with only a subset of models or a single
       model you wish to use with LAMMPS.  Consult the KIM
       documentation for details. :pre

To compile the package, go to the $KIM_DIR directory and execute
make. :l

   % cd $KIM_DIR
   % make examples
   % make :pre

   This builds all Models, Tests, and the openKIM API service routine
   library. The targets defined by the Makefile in this directory include: :pre

   make             -- compiles the API and all Models and Tests
   make all         -- same as `make'
   make examples    -- copy examples into the appropriate directories
                         then do a `make all'
   make openkim-api -- compiles only the API
   make examples-clean -- remove all examples from the MODEL_DRIVERs,
                          MODELs, and TESTs directories. :pre
       
Verify that the compilation was successful by running a Test. :l

   The provided example Tests read in the name of a Model (or Models)
   which they use to perform their calculations.  For most Tests the
   name of the Model can be piped in using an `echo' command.  For
   example, the following Fortran 90 Test reads in one Model: :pre

   % cd $KIM_DIR/TESTs/test_Ar_free_cluster_CLUSTER_F90
   % echo "model_Ar_P_MLJ_CLUSTER_C" | ./test_Ar_free_cluster_CLUSTER_F90 :pre

  (See the README files in the Test directories for an explanation of what 
   the Tests do.) :pre

Each Test (and Model) has its own make file for compiling and linking.
If changes are made to the code, perform step (2) again (from the
$KIM_DIR directory). :l

In case of using a non-standard location for any of the directories
KIM_API, TESTs, or MODELs one or more of the following environment
variables must be set: :l,ole

   KIM_API_DIR
   KIM_TESTS_DIR
   KIM_MODELS_DIR
   KIM_MODEL_DRIVERS_DIR :pre

:line

[Mixing, shift, table, tail correction, restart, rRESPA info]:

This pair style does not support the "pair_modify"_pair_modify.html
mix, shift, table, and tail options.

This pair style does not write its information to "binary restart
files"_restart.html, since KIM stores the the potential parameters.
Thus, you need to re-specify the pair_style and pair_coeff commands in
an input script that reads a restart file.

This pair style can only be used via the {pair} keyword of the
"run_style respa"_run_style.html command.  It does not support the
{inner}, {middle}, {outer} keywords.

:line

[Restrictions:]

This pair style is part of the KIM package.  It is only enabled if
LAMMPS was built with that package.  See the "Making
LAMMPS"_Section_start.html#start_3 section for more info.

This pair style requires the "newton"_newton.html setting to be "off"
for pair interactions.

Currently this pair style only works with LAMMPS metal
"units"_units.html. In the future changes will be made so it can work
with LAMMPS unit choices as well.

[Related commands:]

"pair_coeff"_pair_coeff.html, "pair_style eam"_pair_eam.html

[Default:] none