lammps/doc/pair_kim.html

281 lines
10 KiB
HTML

<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>pair_style kim command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>pair_style kim virialmode model
</PRE>
<UL><LI>virialmode = KIMvirial or LAMMPSvirial
<LI>model = name of KIM model (potential)
</UL>
<P><B>Examples:</B>
</P>
<PRE>pair_style kim KIMvirial model_Ar_P_Morse
pair_coeff * * Ar Ar
</PRE>
<P><B>Description:</B>
</P>
<P>This pair style is a wrapper on the <A HREF = "http://openkim.org">Knowledge Base for Interatomic
Models (KIM)</A> repository of interatomic potentials,
so that they can be used by LAMMPS scripts.
</P>
<P>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.
</P>
<P>The argument <I>virialmode</I> determines how the global virial is
calculated. If <I>KIMvirial</I> is specified, the KIM model performs the
global virial calculation. If <I>LAMMPSvirial</I> is specified, LAMMPS
computes the global virial using its fdotr mechanism.
</P>
<P>The argument <I>model</I> is the name of the KIM model for a specific
potential as KIM defines it. In principle, LAMMPS can invoke any KIM
model. You should get an error or warning message from either LAMMPS
or KIM if there is an incompatibility.
</P>
<P>Only a single pair_coeff command is used with the <I>kim</I> 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:
</P>
<UL><LI>N element names = mapping of KIM elements to atom types
</UL>
<P>As an example, imagine the KIM model supports Si and C atoms. If your
LAMMPS simulation has 4 atom types and you want the 1st 3 to be Si,
and the 4th to be C, you would use the following pair_coeff command:
</P>
<PRE>pair_coeff * * Si Si Si C
</PRE>
<P>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 only be used when a <I>kim</I>
potential is used as part of the <I>hybrid</I> pair style. The NULL values
are placeholders for atom types that will be used with other
potentials.
</P>
<HR>
<P>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.
</P>
<HR>
<P>Here is information on how to build KIM for use with LAMMPS. There is
a directory src/KIM/ with an important file in it: Makefile.lammps.
When you do 'make yes-kim' LAMMPS will use the settings in
src/KIM/Makefile.lammps to find KIM header files and the KIM library
itself for linking purposes. Thus, you should ensure Makefile.lammps
has the correct settings for your system and your build of KIM.
</P>
<P>Consult the KIM documentation for further details on KIM specifics.
</P>
<P>OpenKIM is available for download from <A HREF = "http://openkim.org">this site</A>,
namely http://openkim.org. The tarball you download is
"openkim-api-vX.X.X.tgz", which can be unpacked via
</P>
<PRE>tar xvfz openkim*tgz
</PRE>
<P>The openkim-api-vX.X.X/DOCS directory has further documentation. For
more information on installing KIM and troubleshooting refer to
openkim/INSTALL.
</P>
<P>Here is a brief summary of how to build KIM:
</P>
<OL><LI>If you have previously used the openkim-api package (versions 1.1.1 or
below), it is recommended that you remove all associated environment
variables from your environment. (These include, KIM_DIR, KIM_INTEL,
KIM_SYSTEM32, KIM_DYNAMIC, KIM_API_DIR, KIM_TESTS_DIR,
KIM_MODEL_DRIVERS_DIR, and KIM_MODELS_DIR.) All setting are now
specified in the Makefile.KIM_Config file.
<LI>Set up the Makefile.KIM_Config file
<PRE> (a) Copy the file Makefile.KIM_Config.example to Makefile.KIM_Config
For example, if you untarred the `openkim-api-vX.X.X.tgz' tarball in
your home directory, you would do:
</PRE>
<PRE> % cd $HOME/openkim-api-vX.X.X
% cp Makefile.KIM_Config.example Makefile.KIM_Config
</PRE>
<PRE> The `%' symbol represents the bash sell prompt and should not be typed.
</PRE>
<PRE> (Above `vX.X.X' represents the current release number.)
</PRE>
<PRE> (b) Edit the file Makefile.KIM_Config and set the appropriate value for the
KIM_DIR variable. This must expand to an absolute path. Using the same
assumptions as above, this would be
</PRE>
<PRE> KIM_DIR = $(HOME)/openkim-api-vX.X.X
</PRE>
<PRE> (c) If appropriate, set explicit values for the remaining three
directories
</PRE>
<PRE> KIM_MODEL_DRIVERS_DIR =
KIM_MODELS_DIR =
KIM_TESTS_DIR =
</PRE>
<PRE> If these lines are commented out, defaults will be provided by the
openkim-api make system.
</PRE>
<PRE> (d) Set the value of KIM_COMPILERSUITE. Possible values are `GCC' and
`INTEL'.
</PRE>
<PRE> KIM_COMPILERSUITE = GCC
</PRE>
<PRE> (e) Set the value of KIM_SYSTEMLINKER. Possible values are `linux',
`freebsd', and `darwin'.
</PRE>
<PRE> KIM_SYSTEMLINKER = linux
</PRE>
<PRE> (f) Set the value of KIM_SYSTEMARCH. Possible values are `32bit' and
`64bit'.
</PRE>
<PRE> KIM_SYSTEMARCH = 64bit
</PRE>
<PRE> (g) Set the value of KIM_LINK. Possible values are `dynamic-load',
`dynamic-link', and `static-link'.
</PRE>
<PRE> KIM_LINK = dynamic-load
</PRE>
<PRE> `dynamic-load' is the preferred option. (Unless performance or
other issues require it, you should use dynamic-load.)
`dynamic-link' is like `dynamic-load' but does not use the dl.h
library. This option requires a more complicated Makefile
process, but may improve computation time in some instances.
`static-link' only works with ONE Model and AT MOST ONE Model
Driver (in order to avoid the possibility of symbol
clashes).
</PRE>
<PRE> (h) Set override values for other variables, if necessary, by
adding the desired variable name (after the "# overwrite
default variable values here" line) and filling in appropriate
values.
</PRE>
<PRE> # overwrite default variable values here
</PRE>
<PRE> # overwrite default compiler options
</PRE>
<PRE> CC =
CXX =
FC =
</PRE>
<PRE> # overwrite default compiler option flag lists
FFLAGS =
CCFLAGS =
CXXFLAGS =
LDFLAGS =
</PRE>
<PRE> # overwrite default linker options
LDSHAREDFLAG =
LINKSONAME =
LDWHOLEARCHIVESTARTFLAG =
LDWHOLEARCHIVEENDFLAG =
</PRE>
<PRE> # overwrite default install directories
package_name =
prefix =
libdir =
</PRE>
<LI>In the remainder of the documentation we will use the string $KD to
represent the location of the openkim-api source package (the value of
the KIM_DIR variable discussed above). If you wish to, type the below
commands exactly as written to set the shell variable KD to the
appropriate value:
<PRE> bash:
% export KD=$HOME/openkim-api-vX.X.X
</PRE>
<LI>To compile the package, including the provided examples, change to the
$KD directory and execute `make examples' and then `make':
<PRE> % cd $KD
% make examples
% make
</PRE>
<PRE> This builds all Model Drivers, Models, Tests, and the openkim-api service
routine library. The targets defined by the Makefile in this directory
include:
</PRE>
<PRE> `make' -- compiles the API and all Models and Tests
`make all' -- same as `make'
`make clean' -- will remove appropriate .o, .mod, .a, .so and
executable files
`make install' -- install files to `/usr/local/lib' by default
`make uninstall' -- delete files installed by `make install'
`make openkim-api' -- compiles only the API
`make examples' -- copies examples into the appropriate
directories (no overwrite)
`make examples-force' -- copies examples into the appropriate
directories (overwrite)
`make examples-clean' -- remove all examples from the MODEL_DRIVERS,
MODELS, and TESTS directories.
</PRE>
<LI>Verify that the compilation was successful by running a Test.
<PRE> 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>
<PRE> % cd $KD/TESTs/test_Ar_free_cluster_CLUSTER_F90
% echo "model_Ar_P_MLJ_CLUSTER_C" | ./test_Ar_free_cluster_CLUSTER_F90
</PRE>
<PRE> (See the README files in the Test directories for an explanation of what
the Tests do.)
</PRE>
<LI>Each Test (and Model) has its own make file for compiling and linking.
If changes are made to the code, re-compile (from the $KD
directory).
</OL>
<HR>
<P><B>Mixing, shift, table, tail correction, restart, rRESPA info</B>:
</P>
<P>This pair style does not support the <A HREF = "pair_modify.html">pair_modify</A>
mix, shift, table, and tail options.
</P>
<P>This pair style does not write its information to <A HREF = "restart.html">binary restart
files</A>, since KIM stores 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.
</P>
<P>This pair style can only be used via the <I>pair</I> keyword of the
<A HREF = "run_style.html">run_style respa</A> command. It does not support the
<I>inner</I>, <I>middle</I>, <I>outer</I> keywords.
</P>
<HR>
<P><B>Restrictions:</B>
</P>
<P>This pair style is part of the KIM package. It is only enabled if
LAMMPS was built with that package. See the <A HREF = "Section_start.html#start_3">Making
LAMMPS</A> section for more info.
</P>
<P>This current version of pair_style kim is compatible with the
openkim-api package version 1.2.0 and higher.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "pair_coeff.html">pair_coeff</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>