Merge pull request #1440 from ellio167/kim-simulator-models
Develop native support for KIM simulator models
This commit is contained in:
Axel Kohlmeyer
@ -172,22 +172,17 @@ KIM package :h4,link(kim)
|
||||
|
||||
To build with this package, the KIM library with API v2 must be downloaded
|
||||
and built on your system. It must include the KIM models that you want to
|
||||
use with LAMMPS. If you want to use the "kim_query"_kim_query.html
|
||||
use with LAMMPS. If you want to use the "kim_query"_kim_commands.html
|
||||
command, you also need to have libcurl installed with the matching
|
||||
development headers and the curl-config tool.
|
||||
|
||||
Note that in LAMMPS lingo, a KIM model driver is a pair style
|
||||
(e.g. EAM or Tersoff). A KIM model is a pair style for a particular
|
||||
element or alloy and set of parameters, e.g. EAM for Cu with a
|
||||
specific EAM potential file. Also note that downloading and installing
|
||||
the KIM API library with all its models, may take a long time (10s of
|
||||
minutes to hours) to build. Of course you only need to do that once.
|
||||
See "Obtaining KIM Models"_http://openkim.org/doc/usage/obtaining-models to
|
||||
learn how to install a pre-build binary of the OpenKIM Repository of Models.
|
||||
See the list of all KIM models here: https://openkim.org/browse/models
|
||||
|
||||
See the list of KIM model drivers here:
|
||||
https://openkim.org/browse/model-drivers/alphabetical
|
||||
|
||||
See the list of all KIM models here:
|
||||
https://openkim.org/browse/models/by-model-drivers
|
||||
(Also note that when downloading and installing from source
|
||||
the KIM API library with all its models, may take a long time (tens of
|
||||
minutes to hours) to build. Of course you only need to do that once.)
|
||||
|
||||
[CMake build]:
|
||||
|
||||
|
||||
@ -68,7 +68,9 @@ An alphabetic list of all general LAMMPS commands.
|
||||
"improper_style"_improper_style.html,
|
||||
"include"_include.html,
|
||||
"jump"_jump.html,
|
||||
"kim_query"_kim_query.html,
|
||||
"kim_init"_kim_commands.html,
|
||||
"kim_interactions"_kim_commands.html,
|
||||
"kim_query"_kim_commands.html,
|
||||
"kspace_modify"_kspace_modify.html,
|
||||
"kspace_style"_kspace_style.html,
|
||||
"label"_label.html,
|
||||
|
||||
@ -5785,6 +5785,16 @@ definitions. :dd
|
||||
|
||||
The data file header lists improper but no improper types. :dd
|
||||
|
||||
{Incompatible KIM Simulator Model} :dt
|
||||
|
||||
The requested KIM Simulator Model was defined for a different MD code
|
||||
and thus is not compatible with LAMMPS. :dd
|
||||
|
||||
{Incompatible units for KIM Simulator Model} :dt
|
||||
|
||||
The selected unit style is not compatible with the requested KIM
|
||||
Simulator Model. :dd
|
||||
|
||||
{Incomplete use of variables in create_atoms command} :dt
|
||||
|
||||
The var and set options must be used together. :dd
|
||||
@ -7055,6 +7065,12 @@ The atom style defined does not have this attribute. :dd
|
||||
|
||||
The atom style defined does not have these attributes. :dd
|
||||
|
||||
{KIM Simulator Model has no Model definition} :dt
|
||||
|
||||
There is no model definition (key: model-defn) in the KIM Simulator
|
||||
Model. Please contact the OpenKIM database maintainers to verify
|
||||
and potentially correct this. :dd
|
||||
|
||||
{KOKKOS package does not yet support comm_style tiled} :dt
|
||||
|
||||
Self-explanatory. :dd
|
||||
@ -7559,6 +7575,18 @@ Self-explanatory. :dd
|
||||
|
||||
Self-explanatory. :dd
|
||||
|
||||
{Must use 'kim_style init' command before simulation box is defined} :dt
|
||||
|
||||
Self-explanatory. :dd
|
||||
|
||||
{Must use 'kim_style define' command after simulation box is defined} :dt
|
||||
|
||||
Self-explanatory. :dd
|
||||
|
||||
{Must use 'kim_style init' command before 'kim_style define'} :dt
|
||||
|
||||
Self-explanatory. :dd
|
||||
|
||||
{Must use 'kspace_modify pressure/scalar no' for rRESPA with kspace_style MSM} :dt
|
||||
|
||||
The kspace scalar pressure option cannot (yet) be used with rRESPA. :dd
|
||||
@ -9502,6 +9530,11 @@ See the "read_data extra/special/per/atom" command
|
||||
for info on how to leave space in the special bonds
|
||||
list to allow for additional bonds to be formed. :dd
|
||||
|
||||
{Species XXX is not supported by this KIM Simulator Model} :dt
|
||||
|
||||
The kim_style define command was referencing a species that is not
|
||||
present in the requested KIM Simulator Model. :dd
|
||||
|
||||
{Specified processors != physical processors} :dt
|
||||
|
||||
The 3d grid of processors defined by the processors command does not
|
||||
|
||||
@ -73,7 +73,7 @@ granregion: use of fix wall/region/gran as boundary on granular particles
|
||||
hugoniostat: Hugoniostat shock dynamics
|
||||
hyper: global and local hyperdynamics of diffusion on Pt surface
|
||||
indent: spherical indenter into a 2d solid
|
||||
kim: use of potentials in Knowledge Base for Interatomic Models (KIM)
|
||||
kim: use of potentials from the "OpenKIM Repository"_openkim
|
||||
latte: examples for using fix latte for DFTB via the LATTE library
|
||||
meam: MEAM test for SiC and shear (same as shear examples)
|
||||
melt: rapid melt of 3d LJ system
|
||||
@ -153,3 +153,5 @@ illustrate how to use the command(s) provided in that package. Many
|
||||
of the sub-directories have their own README files which give further
|
||||
instructions. See the "Packages_details"_Packages_details.html doc
|
||||
page for more info on specific USER packages.
|
||||
|
||||
:link(openkim,https://openkim.org)
|
||||
|
||||
@ -10,47 +10,34 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
|
||||
Download an executable for Mac :h3
|
||||
|
||||
LAMMPS can be downloaded, built, and configured for OS X on a Mac with
|
||||
"Homebrew"_homebrew. Only four of the LAMMPS packages are unavailable
|
||||
at this time because of additional needs not yet met: KIM, GPU,
|
||||
USER-INTEL, USER-ATC.
|
||||
"Homebrew"_homebrew. The following LAMMPS packages are unavailable at this
|
||||
time because of additional needs not yet met: GPU, KOKKOS, LATTE, MSCG,
|
||||
MESSAGE, MPIIO POEMS VORONOI.
|
||||
|
||||
After installing Homebrew, you can install LAMMPS on your system with
|
||||
the following commands:
|
||||
|
||||
% brew tap homebrew/science
|
||||
% brew install lammps # serial version
|
||||
% brew install lammps --with-mpi # mpi support :pre
|
||||
% brew install lammps :pre
|
||||
|
||||
This will install the executable "lammps", a python module named
|
||||
"lammps", and additional resources with all the standard packages. To
|
||||
get the location of the additional resources type this:
|
||||
|
||||
% brew info lammps :pre
|
||||
|
||||
This command also tells you additional installation options available.
|
||||
The user-packages are available as options, just install them like
|
||||
this example for the USER-OMP package:
|
||||
|
||||
% brew install lammps --enable-user-omp :pre
|
||||
|
||||
It is usually best to install LAMMPS with the most up to date source
|
||||
files, which can be done with the "--HEAD" option:
|
||||
|
||||
% brew install lammps --HEAD :pre
|
||||
|
||||
To re-install the LAMMPS HEAD, run this command occasionally (make sure
|
||||
to use the desired options).
|
||||
|
||||
% brew install --force lammps --HEAD $\{options\} :pre
|
||||
This will install the executables "lammps_serial" and "lammps_mpi", as well as
|
||||
the LAMMPS "doc", "potentials", "tools", "bench", and "examples" directories.
|
||||
|
||||
Once LAMMPS is installed, you can test the installation with the
|
||||
Lennard-Jones benchmark file:
|
||||
|
||||
% brew test lammps -v :pre
|
||||
|
||||
The LAMMPS binary is built with the "KIM package"_Build_extras#kim which
|
||||
results in Homebrew also installing the `kim-api` binaries when LAMMPS is
|
||||
installed. In order to use potentials from "openkim.org"_openkim, you can
|
||||
install the `openkim-models` package
|
||||
|
||||
% brew install openkim-models :pre
|
||||
|
||||
If you have problems with the installation you can post issues to
|
||||
"this link"_homebrew.
|
||||
|
||||
Thanks to Derek Thomas (derekt at cello.t.u-tokyo.ac.jp) for setting
|
||||
up the Homebrew capability.
|
||||
:link(homebrew,https://github.com/Homebrew/homebrew-science/issues)
|
||||
:link(homebrew,https://github.com/Homebrew/homebrew-core/issues)
|
||||
:link(openkim,https://openkim.org)
|
||||
|
||||
@ -92,8 +92,8 @@ commands)
|
||||
implicit solvent potentials: hydrodynamic lubrication, Debye
|
||||
force-field compatibility with common CHARMM, AMBER, DREIDING, \
|
||||
OPLS, GROMACS, COMPASS options
|
||||
access to "KIM archive"_http://openkim.org of potentials via \
|
||||
"pair kim"_pair_kim.html
|
||||
access to the "OpenKIM Repository"_http://openkim.org of potentials via \
|
||||
"kim_init, kim_interactions, and kim_query"_kim_commands.html commands
|
||||
hybrid potentials: multiple pair, bond, angle, dihedral, improper \
|
||||
potentials can be used in one simulation
|
||||
overlaid potentials: superposition of multiple pair potentials :ul
|
||||
|
||||
@ -338,22 +338,37 @@ KIM package :link(PKG-KIM),h4
|
||||
|
||||
[Contents:]
|
||||
|
||||
A "pair_style kim"_pair_kim.html command which is a wrapper on the
|
||||
Knowledge Base for Interatomic Models (KIM) repository of interatomic
|
||||
potentials, enabling any of them to be used in LAMMPS simulations.
|
||||
Also a "kim_query"_kim_query.html command, which allows to query
|
||||
the OpenKIM database for stored properties.
|
||||
This package contains a set of commands that serve as a wrapper on the
|
||||
"Open Knowledgebase of Interatomic Models (OpenKIM)"_https://openkim.org
|
||||
repository of interatomic models (IMs)
|
||||
enabling compatible ones to be used in LAMMPS simulations.
|
||||
This includes "kim_init and kim_interactions"_kim_commands.html
|
||||
commands to select, initialize and instantiate the IM, and a
|
||||
"kim_query"_kim_commands.html command to perform web queries
|
||||
for material property predictions of OpenKIM IMs.
|
||||
Support for KIM IMs that conform to the
|
||||
"KIM Application Programming Interface (API)"_https://openkim.org/kim-api/
|
||||
is provided by the "pair_style kim"_pair_kim.html command.
|
||||
|
||||
To use this package you must have the KIM library available on your
|
||||
system.
|
||||
NOTE: The command {pair_style kim} is called by {kim_interactions} and
|
||||
is not recommended to be directly used in input scripts.
|
||||
|
||||
To use this package you must have the KIM API library available on your
|
||||
system. The KIM API is available for download on the
|
||||
"OpenKIM website"_https://openkim.org/kim-api/.
|
||||
When installing LAMMPS from binary, the kim-api package
|
||||
is a dependency that is automatically downloaded and installed.
|
||||
|
||||
Information about the KIM project can be found at its website:
|
||||
https://openkim.org. The KIM project is led by Ellad Tadmor and Ryan
|
||||
Elliott (U Minnesota).
|
||||
"https://openkim.org"_https://openkim.org.
|
||||
The KIM project is led by Ellad Tadmor and Ryan Elliott (U Minnesota)
|
||||
and is funded by the "National Science Foundation"_https://www.nsf.gov/.
|
||||
|
||||
[Authors:] Ryan Elliott (U Minnesota) is the main developer for the KIM
|
||||
API which the "pair_style kim"_pair_kim.html command uses. He
|
||||
developed the pair style.
|
||||
API and the {pair_style kim} command. Axel Kohlmeyer (Temple U) and
|
||||
Ellad Tadmor (U Minnesota) contributed to the "kim_commands"_kim_commands.html
|
||||
interface in close collaboration with Ryan Elliott.
|
||||
|
||||
|
||||
[Install:]
|
||||
|
||||
@ -363,10 +378,11 @@ extras"_Build_extras.html doc page.
|
||||
|
||||
[Supporting info:]
|
||||
|
||||
"kim_commands"_kim_commands.html
|
||||
"pair_style kim"_pair_kim.html
|
||||
src/KIM: filenames -> commands
|
||||
src/KIM/README
|
||||
lib/kim/README
|
||||
"pair_style kim"_pair_kim.html
|
||||
examples/kim :ul
|
||||
|
||||
:line
|
||||
@ -984,9 +1000,9 @@ USER-ADIOS package :link(PKG-USER-ADIOS),h4
|
||||
|
||||
[Contents:]
|
||||
|
||||
ADIOS is a high-performance I/O library. This package implements the
|
||||
ADIOS is a high-performance I/O library. This package implements the
|
||||
dump "atom/adios" and dump "custom/adios" commands to write data using
|
||||
the ADIOS library.
|
||||
the ADIOS library.
|
||||
|
||||
[Authors:] Norbert Podhorszki (ORNL) from the ADIOS developer team.
|
||||
|
||||
|
||||
@ -53,7 +53,7 @@ Commands :h1
|
||||
include
|
||||
info
|
||||
jump
|
||||
kim_query
|
||||
kim_commands
|
||||
kspace_modify
|
||||
kspace_style
|
||||
label
|
||||
|
||||
@ -177,7 +177,7 @@ compute"_Commands_compute.html doc page are followed by one or more of
|
||||
"angle"_compute_angle.html - energy of each angle sub-style
|
||||
"angle/local"_compute_angle_local.html - theta and energy of each angle
|
||||
"angmom/chunk"_compute_angmom_chunk.html - angular momentum for each chunk
|
||||
"basal/atom"_compute_basal_atom.html - calculates the hexagonal close-packed “c” lattice vector of each atom
|
||||
"basal/atom"_compute_basal_atom.html - calculates the hexagonal close-packed "c" lattice vector of each atom
|
||||
"body/local"_compute_body_local.html - attributes of body sub-particles
|
||||
"bond"_compute_bond.html - energy of each bond sub-style
|
||||
"bond/local"_compute_bond_local.html - distance and energy of each bond
|
||||
|
||||
@ -149,8 +149,7 @@ meaning of these parameters:
|
||||
"spin/neel"_pair_spin_neel.html: coulombic_cutoff: type global:
|
||||
"table"_pair_table.html: table_cutoff: type pairs:
|
||||
"ufm"_pair_ufm.html: epsilon,sigma: type pairs:
|
||||
"soft"_pair_soft.html: a: type pairs:
|
||||
"kim"_pair_kim.html: PARAM_FREE_*:i,j,...: global :tb(c=3,s=:)
|
||||
"soft"_pair_soft.html: a: type pairs: :tb(c=3,s=:)
|
||||
|
||||
NOTE: It is easy to add new pairwise potentials and their parameters
|
||||
to this list. All it typically takes is adding an extract() method to
|
||||
|
||||
522
doc/src/kim_commands.txt
Normal file
522
doc/src/kim_commands.txt
Normal file
@ -0,0 +1,522 @@
|
||||
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
|
||||
|
||||
:link(lws,http://lammps.sandia.gov)
|
||||
:link(ld,Manual.html)
|
||||
:link(lc,Commands_all.html)
|
||||
|
||||
:line
|
||||
|
||||
kim_init command :h3
|
||||
kim_interactions command :h3
|
||||
kim_query command :h3
|
||||
|
||||
[Syntax:]
|
||||
|
||||
kim_init model user_units unitarg
|
||||
kim_interactions typeargs
|
||||
kim_query variable formatarg query_function queryargs :pre
|
||||
|
||||
model = name of the KIM interatomic model (the KIM ID for models archived in OpenKIM)
|
||||
user_units = the LAMMPS "units"_units.html style assumed in the LAMMPS input script
|
||||
unitarg = {unit_conversion_mode} (optional)
|
||||
typeargs = atom type to species mapping (one entry per atom type) or {fixed_types} for models with a preset fixed mapping
|
||||
variable = name of a (string style) variable where the result of the query is stored
|
||||
formatarg = {split} (optional)
|
||||
query_function = name of the OpenKIM web API query function to be used
|
||||
queryargs = a series of {keyword=value} pairs that represent the web query; supported keywords depend on the query function :ul
|
||||
|
||||
|
||||
[Examples:]
|
||||
|
||||
kim_init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal
|
||||
kim_interactions Si
|
||||
kim_init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_000 real
|
||||
kim_init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_000 metal unit_conversion_mode
|
||||
kim_interactions C H O
|
||||
Sim_LAMMPS_IFF_PCFF_HeinzMishraLinEmami_2015Ver1v5_FccmetalsMineralsSolvents Polymers__SM_039297821658_000 real
|
||||
kim_interactions fixed_types
|
||||
kim_query a0 get_lattice_constant_cubic crystal=\["fcc"\] species=\["Al"\] units=\["angstrom"\] :pre
|
||||
|
||||
[Description:]
|
||||
|
||||
The set of {kim_commands} provide a high-level wrapper around the
|
||||
"Open Knowledgebase of Interatomic Models (OpenKIM)"_https://openkim.org
|
||||
repository of interatomic models (IMs) (potentials and force fields),
|
||||
so that they can be used by LAMMPS scripts. These commands do not implement
|
||||
any computations directly, but rather generate LAMMPS input commands based
|
||||
on the information retrieved from the OpenKIM repository to initialize and
|
||||
activate OpenKIM IMs and query their predictions for use in the LAMMPS script.
|
||||
All LAMMPS input commands generated and executed by {kim_commands} are
|
||||
echoed to the LAMMPS log file.
|
||||
|
||||
Benefits of Using OpenKIM IMs :h4
|
||||
|
||||
Employing OpenKIM IMs provides LAMMPS users with multiple benefits:
|
||||
|
||||
Reliability :h5
|
||||
|
||||
All content archived in OpenKIM is reviewed by the "KIM Editor"_https://openkim.org/governance/ for quality.
|
||||
IMs in OpenKIM are archived with full provenance control. Each is associated with a maintainer responsible for the integrity of the content. All changes are tracked and recorded.
|
||||
IMs in OpenKIM are exhaustively tested using "KIM Tests"_https://openkim.org/doc/evaluation/kim-tests/ that compute a host of material properties, and "KIM Verification Checks"_https://openkim.org/doc/evaluation/kim-verification-checks/ that provide the user with information on various aspects of the IM behavior and coding correctness. This information is displayed on the IM's page accessible through the "OpenKIM browse interface"_https://openkim.org/browse. :ul
|
||||
|
||||
Reproducibility :h5
|
||||
|
||||
Each IM in OpenKIM is issued a unique identifier ("KIM ID"_https://openkim.org/doc/schema/kim-ids/), which includes a version number (last three digits). Any changes that can result in different numerical values lead to a version increment in the KIM ID. This makes it possible to reproduce simulations since the specific version of a specific IM used can be retrieved using its KIM ID.
|
||||
OpenKIM is a member organization of "DataCite"_https://datacite.org/ and issues digital object identifiers (DOIs) to all IMs archived in OpenKIM. This makes it possible to cite the IM code used in a simulation in a publications to give credit to the developers and further facilitate reproducibility. :ul
|
||||
|
||||
Convenience :h5
|
||||
|
||||
IMs in OpenKIM are distributed in binary form along with LAMMPS and can be used in a LAMMPS input script simply by providing their KIM ID in the {kim_init} command documented on this page.
|
||||
The {kim_query} web query tool provides the ability to use the predictions of IMs for supported material properties (computed via "KIM Tests"_https://openkim.org/doc/evaluation/kim-tests/) as part of a LAMMPS input script setup and analysis.
|
||||
Support is provided for unit conversion between the "unit style"_units.html used in the LAMMPS input script and the units required by the OpenKIM IM. This makes it possible to use a single input script with IMs using different units without change and minimizes the likelihood of errors due to incompatible units. :ul
|
||||
|
||||
:link(IM_types)
|
||||
Types of IMs in OpenKIM :h4
|
||||
|
||||
There are two types of IMs archived in OpenKIM:
|
||||
|
||||
The first type is called a {KIM Portable Model} (PM). A KIM PM is an independent computer implementation of an IM written in one of the languages supported by KIM (C, C++, Fortran) that conforms to the KIM Application Programming Interface ("KIM API"_https://openkim.org/kim-api/) Portable Model Interface (PMI) standard. A KIM PM will work seamlessly with any simulation code that supports the KIM API/PMI standard (including LAMMPS; see "complete list of supported codes"_https://openkim.org/projects-using-kim/).
|
||||
The second type is called a {KIM Simulator Model} (SM). A KIM SM is an IM that is implemented natively within a simulation code ({simulator}) that supports the KIM API Simulator Model Interface (SMI); in this case LAMMPS. A separate SM package is archived in OpenKIM for each parameterization of the IM, which includes all of the necessary parameter files, LAMMPS commands, and metadata (supported species, units, etc.) needed to run the IM in LAMMPS. :ol
|
||||
|
||||
With these two IM types, OpenKIM can archive and test almost all IMs that
|
||||
can be used by LAMMPS. (It is easy to contribute new IMs to OpenKIM, see
|
||||
the "upload instructions"_https://openkim.org/doc/repository/adding-content/.)
|
||||
|
||||
OpenKIM IMs are uniquely identified by a
|
||||
"KIM ID"_https://openkim.org/doc/schema/kim-ids/.
|
||||
The extended KIM ID consists of
|
||||
a human-readable prefix identifying the type of IM, authors, publication year,
|
||||
and supported species, separated by two underscores from the KIM ID itself,
|
||||
which begins with an IM code
|
||||
({MO} for a KIM Portable Model, and {SM} for a KIM Simulator Model)
|
||||
followed by a unique 12-digit code and a 3-digit version identifier.
|
||||
By convention SM prefixes begin with {Sim_} to readily identify them.
|
||||
|
||||
SW_StillingerWeber_1985_Si__MO_405512056662_005
|
||||
Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_000 :pre
|
||||
|
||||
Each OpenKIM IM has a dedicated "Model Page" on "OpenKIM"_https://openkim.org
|
||||
providing all the information on the IM including a title, description,
|
||||
authorship and citation information, test and verification check results,
|
||||
visualizations of results, a wiki with documentation and user comments, and
|
||||
access to raw files, and other information.
|
||||
The URL for the Model Page is constructed from the
|
||||
"extended KIM ID"_https://openkim.org/doc/schema/kim-ids/ of the IM:
|
||||
|
||||
https://openkim.org/id/extended_KIM_ID
|
||||
:pre
|
||||
|
||||
For example for the Stillinger-Weber potential
|
||||
listed above the Model Page is located at:
|
||||
|
||||
"https://openkim.org/id/SW_StillingerWeber_1985_Si__MO_405512056662_005"_https://openkim.org/id/SW_StillingerWeber_1985_Si__MO_405512056662_005
|
||||
:pre
|
||||
|
||||
See the "current list of KIM PMs and SMs archived in OpenKIM"_https://openkim.org/browse/models/by-species.
|
||||
This list is sorted by species and can be filtered to display only
|
||||
IMs for certain species combinations.
|
||||
|
||||
See "Obtaining KIM Models"_http://openkim.org/doc/usage/obtaining-models to
|
||||
learn how to install a pre-build binary of the OpenKIM Repository of Models.
|
||||
|
||||
NOTE: It is also possible to locally install IMs not archived in OpenKIM,
|
||||
in which case their names do not have to conform to the KIM ID format.
|
||||
|
||||
Using OpenKIM IMs with LAMMPS :h4
|
||||
|
||||
Two commands are employed when using OpenKIM IMs, one to select the
|
||||
IM and perform necessary initialization ({kim_init}), and the second
|
||||
to set up the IM for use by executing any necessary LAMMPS commands
|
||||
({kim_interactions}). Both are required.
|
||||
|
||||
See the {examples/kim} directory for example input scripts that use KIM PMs
|
||||
and KIM SMs.
|
||||
|
||||
OpenKIM IM Initialization ({kim_init}) :h5
|
||||
|
||||
The {kim_init} mode command must be issued [before]
|
||||
the simulation box is created (normally at the top of the file).
|
||||
This command sets the OpenKIM IM that will be used and may issue
|
||||
additional commands changing LAMMPS default settings that are required
|
||||
for using the selected IM (such as "units"_units.html or
|
||||
"atom_style"_atom_style.html). If needed, those settings can be overridden,
|
||||
however, typically a script containing a {kim_init} command
|
||||
would not include {units} and {atom_style} commands.
|
||||
|
||||
The required arguments of {kim_init} are the {model} name of the
|
||||
IM to be used in the simulation (for an IM archived in OpenKIM this is
|
||||
its "extended KIM ID"_https://openkim.org/doc/schema/kim-ids/, and
|
||||
the {user_units}, which are the LAMMPS "units style"_units.html used
|
||||
in the input script. (Any dimensioned numerical values in the input
|
||||
script and values read in from files are expected to be in the
|
||||
{user_units} system.)
|
||||
|
||||
The selected IM can be either a "KIM PM or a KIM SM"_#IM_types.
|
||||
For a KIM SM, the {kim_init} command verifies that the SM is designed
|
||||
to work with LAMMPS (and not another simulation code).
|
||||
In addition, the LAMMPS version used for defining
|
||||
the SM and the LAMMPS version being currently run are
|
||||
printed to help diagnose any incompatible changes to input script or
|
||||
command syntax between the two LAMMPS versions.
|
||||
|
||||
Based on the selected model {kim_init} may modify the
|
||||
"atom_style"_atom_style.html.
|
||||
Some SMs have requirements for this setting. If this is the case, then
|
||||
{atom_style} will be set to the required style. Otherwise, the value is left
|
||||
unchanged (which in the absence of an {atom_style} command in the input script
|
||||
is the "default atom_style value"_atom_style.html).
|
||||
|
||||
Regarding units, the {kim_init} command behaves in different ways depending
|
||||
on whether or not {unit conversion mode} is activated as indicated by the
|
||||
optional {unitarg} argument.
|
||||
If unit conversion mode is [not] active, then {user_units} must
|
||||
either match the required units of the IM or the IM must be able
|
||||
to adjust its units to match. (The latter is only possible with some KIM PMs;
|
||||
SMs can never adjust their units.) If a match is possible, the LAMMPS
|
||||
"units"_units.html command is called to set the units to
|
||||
{user_units}. If the match fails, the simulation is terminated with
|
||||
an error.
|
||||
|
||||
Here is an example of a LAMMPS script to compute the cohesive energy
|
||||
of a face-centered cubic (fcc) lattice for the Ercolessi and Adams (1994)
|
||||
potential for Al:
|
||||
|
||||
kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal
|
||||
boundary p p p
|
||||
lattice fcc 4.032
|
||||
region simbox block 0 1 0 1 0 1 units lattice
|
||||
create_box 1 simbox
|
||||
create_atoms 1 box
|
||||
mass 1 26.981539
|
||||
kim_interactions Al
|
||||
run 0
|
||||
variable Ec equal (pe/count(all))/$\{_u_energy\}
|
||||
print "Cohesive Energy = $\{EcJ\} eV"
|
||||
:pre
|
||||
|
||||
The above script will end with an error in the {kim_init} line if the
|
||||
IM is changed to another potential for Al that does not work with {metal}
|
||||
units. To address this {kim_init} offers the {unit_conversion_mode}.
|
||||
If unit conversion mode {is} active, then {kim_init} calls the LAMMPS
|
||||
"units"_units.html command to set the units to the IM's required or
|
||||
preferred units. Conversion factors between the IM's units and the {user_units}
|
||||
are defined for all "physical quantities"_units.html (mass, distance, etc.).
|
||||
(Note that converting to or from the "lj" unit style is not supported.)
|
||||
These factors are stored as "internal style variables"_variable.html with
|
||||
the following standard names:
|
||||
|
||||
_u_mass
|
||||
_u_distance
|
||||
_u_time
|
||||
_u_energy
|
||||
_u_velocity
|
||||
_u_force
|
||||
_u_torque
|
||||
_u_temperature
|
||||
_u_pressure
|
||||
_u_viscosity
|
||||
_u_charge
|
||||
_u_dipole
|
||||
_u_efield
|
||||
_u_density :pre
|
||||
|
||||
If desired, the input script can be designed to work with these conversion
|
||||
factors so that the script will work without change with any OpenKIM IM.
|
||||
(This approach is used in the
|
||||
"OpenKIM Testing Framework"_https://openkim.org/doc/evaluation/kim-tests/.)
|
||||
For example, the script given above for the cohesive energy of fcc Al
|
||||
can be rewritten to work with any IM regardless of units. The following
|
||||
script constructs an fcc lattice with a lattice parameter defined in
|
||||
meters, computes the total energy, and prints the cohesive energy in
|
||||
Joules regardless of the units of the IM.
|
||||
|
||||
kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 si unit_conversion_mode
|
||||
boundary p p p
|
||||
lattice fcc 4.032e-10*$\{_u_distance\}
|
||||
region simbox block 0 1 0 1 0 1 units lattice
|
||||
create_box 1 simbox
|
||||
create_atoms 1 box
|
||||
mass 1 4.480134e-26*$\{_u_mass\}
|
||||
kim_interactions Al
|
||||
run 0
|
||||
variable Ec_in_J equal (pe/count(all))/$\{_u_energy\}
|
||||
print "Cohesive Energy = $\{Ec_in_J\} J" :pre
|
||||
|
||||
Note the multiplication by $\{_u_distance\} and $\{_u_mass\} to convert
|
||||
from SI units (specified in the {kim_init} command) to whatever units the
|
||||
IM uses (metal in this case), and the division by $\{_u_energy\}
|
||||
to convert from the IM's energy units to SI units (Joule). This script
|
||||
will work correctly for any IM for Al (KIM PM or SM) selected by the
|
||||
{kim_init} command.
|
||||
|
||||
Care must be taken to apply unit conversion to dimensional variables read in
|
||||
from a file. For example if a configuration of atoms is read in from a
|
||||
dump file using the "read_dump"_read_dump.html command, the following can
|
||||
be done to convert the box and all atomic positions to the correct units:
|
||||
|
||||
variable xyfinal equal xy*$\{_u_distance\}
|
||||
variable xzfinal equal xz*$\{_u_distance\}
|
||||
variable yzfinal equal yz*$\{_u_distance\}
|
||||
change_box all x scale $\{_u_distance\} &
|
||||
y scale $\{_u_distance\} &
|
||||
z scale $\{_u_distance\} &
|
||||
xy final $\{xyfinal\} &
|
||||
xz final $\{xzfinal\} &
|
||||
yz final $\{yzfinal\} &
|
||||
remap :pre
|
||||
|
||||
NOTE: Unit conversion will only work if the conversion factors are placed in
|
||||
all appropriate places in the input script. It is up to the user to do this
|
||||
correctly.
|
||||
|
||||
OpenKIM IM Execution ({kim_interactions}) :h5
|
||||
|
||||
The second and final step in using an OpenKIM IM is to execute the
|
||||
{kim_interactions} command. This command must be preceded by a {kim_init}
|
||||
command and a command that defines the number of atom types {N} (such as
|
||||
"create_box"_create_box.html).
|
||||
The {kim_interactions} command has one argument {typeargs}. This argument
|
||||
contains either a list of {N} chemical species, which defines a mapping between
|
||||
atom types in LAMMPS to the available species in the OpenKIM IM, or the
|
||||
keyword {fixed_types} for models that have a preset fixed mapping (i.e.
|
||||
the mapping between LAMMPS atom types and chemical species is defined by
|
||||
the model and cannot be changed). In the latter case, the user must consult
|
||||
the model documentation to see how many atom types there are and how they
|
||||
map to the chemical species.
|
||||
|
||||
For example, consider an OpenKIM IM that supports Si and C species.
|
||||
If the LAMMPS simulation has four atom types, where the first three are Si,
|
||||
and the fourth is C, the following {kim_interactions} command would be used:
|
||||
|
||||
kim_interactions Si Si Si C
|
||||
:pre
|
||||
|
||||
Alternatively, for a model with a fixed mapping the command would be:
|
||||
|
||||
kim_interactions fixed_types
|
||||
:pre
|
||||
|
||||
The {kim_interactions} command performs all the necessary steps to set up
|
||||
the OpenKIM IM selected in the {kim_init} command. The specific actions depend
|
||||
on whether the IM is a KIM PM or a KIM SM. For a KIM PM,
|
||||
a "pair_style kim"_pair_kim.html command is executed followed by
|
||||
the appropriate {pair_coeff} command. For example, for the
|
||||
Ercolessi and Adams (1994) KIM PM for Al set by the following commands:
|
||||
|
||||
kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal
|
||||
...
|
||||
... box specification lines skipped
|
||||
...
|
||||
kim_interactions Al :pre
|
||||
|
||||
the {kim_interactions} command executes the following LAMMPS input commands:
|
||||
|
||||
pair_style kim EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005
|
||||
pair_coeff * * Al :pre
|
||||
|
||||
For a KIM SM, the generated input commands may be more complex
|
||||
and require that LAMMPS is built with the required packages included
|
||||
for the type of potential being used. The set of commands to be executed
|
||||
is defined in the SM specification file, which is part of the SM package.
|
||||
For example, for the Strachan et al. (2003) ReaxFF SM
|
||||
set by the following commands:
|
||||
|
||||
kim_init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_000 real
|
||||
...
|
||||
... box specification lines skipped
|
||||
...
|
||||
kim_interactions C H N O :pre
|
||||
|
||||
the {kim_interactions} command executes the following LAMMPS input commands:
|
||||
|
||||
pair_style reax/c lmp_control safezone 2.0 mincap 100
|
||||
pair_coeff * * ffield.reax.rdx C H N O
|
||||
fix reaxqeq all qeq/reax 1 0.0 10.0 1.0e-6 param.qeq :pre
|
||||
|
||||
Note that the files {lmp_control}, {ffield.reax.rdx} and {param.qeq}
|
||||
are specific to the Strachan et al. (2003) ReaxFF parameterization
|
||||
and are archived as part of the SM package in OpenKIM.
|
||||
Note also that parameters like cutoff radii and charge tolerances,
|
||||
which have an effect on IM predictions, are also included in the
|
||||
SM definition ensuring reproducibility.
|
||||
|
||||
NOTE: When using {kim_init} and {kim_interactions} to select
|
||||
and set up an OpenKIM IM, other LAMMPS commands
|
||||
for the same functions (such as pair_style, pair_coeff, bond_style,
|
||||
bond_coeff, fixes related to charge equilibration, etc.) should normally
|
||||
not appear in the input script.
|
||||
|
||||
Using OpenKIM Web Queries in LAMMPS ({kim_query}) :h5
|
||||
|
||||
The {kim_query} command performs a web query to retrieve the predictions
|
||||
of the IM set by {kim_init} for material properties archived in
|
||||
"OpenKIM"_https://openkim.org. The {kim_query} command must be preceded
|
||||
by a {kim_init} command. The result of the query is stored in a
|
||||
"string style variable"_variable.html, the name of which is given as the first
|
||||
argument of the {kim_query command}. (For the case of multiple
|
||||
return values, the optional {split} keyword can be used after the
|
||||
variable name to separate the results into multiple variables; see
|
||||
the "example"_#split_example below.)
|
||||
The second required argument {query_function} is the name of the
|
||||
query function to be called (e.g. {get_lattice_constant_cubic}).
|
||||
All following "arguments"_Commands_parse.html are parameters handed over to
|
||||
the web query in the format {keyword=value}, where {value} is always
|
||||
an array of one or more comma-separated items in brackets.
|
||||
The list of supported keywords and the type and format of their values
|
||||
depend on the query function used. The current list of query functions
|
||||
is available on the OpenKIM webpage at
|
||||
"https://openkim.org/doc/repository/kim-query"_https://openkim.org/doc/repository/kim-query.
|
||||
|
||||
NOTE: All query functions require the {model} keyword, which identifies
|
||||
the IM whose predictions are being queried. This keyword is automatically
|
||||
generated by {kim_query} based on the IM set in {kim_init} and must not
|
||||
be specified as an argument to {kim_query}.
|
||||
|
||||
NOTE: Each {query_function} is associated with a default method (implemented
|
||||
as a "KIM Test"_https://openkim.org/doc/evaluation/kim-tests/)
|
||||
used to compute this property. In cases where there are multiple
|
||||
methods in OpenKIM for computing a property, a {method} keyword can
|
||||
be provided to select the method of choice. See the
|
||||
"query documentation"_https://openkim.org/doc/repository/kim-query
|
||||
to see which methods are available for a given {query function}.
|
||||
|
||||
{kim_query} Usage Examples and Further Clarifications: :h6
|
||||
|
||||
The data obtained by {kim_query} commands can be used as part of the setup
|
||||
or analysis phases of LAMMPS simulations. Some examples are given below.
|
||||
|
||||
[Define an equilibrium fcc crystal]
|
||||
|
||||
kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal
|
||||
boundary p p p
|
||||
kim_query a0 get_lattice_constant_cubic crystal=\["fcc"\] species=\["Al"\] units=\["angstrom"\]
|
||||
lattice fcc $\{a0\}
|
||||
... :pre
|
||||
|
||||
The {kim_query} command retrieves from "OpenKIM"_https://openkim.org
|
||||
the equilibrium lattice constant predicted by the Ercolessi and Adams (1994)
|
||||
potential for the fcc structure and places it in
|
||||
variable {a0}. This variable is then used on the next line to set up the
|
||||
crystal. By using {kim_query}, the user is saved the trouble and possible
|
||||
error of tracking this value down, or of having to perform an energy
|
||||
minimization to find the equilibrium lattice constant.
|
||||
|
||||
Note that in {unit_conversion_mode} the results obtained from a
|
||||
{kim_query} would need to be converted to the appropriate units system.
|
||||
For example, in the above script, the lattice command would need to be
|
||||
changed to: "lattice fcc $\{a0\}*$\{_u_distance\}".
|
||||
|
||||
:link(split_example)
|
||||
[Define an equilibrium hcp crystal]
|
||||
|
||||
kim_init EAM_Dynamo_Mendelev_2007_Zr__MO_848899341753_000 metal
|
||||
boundary p p p
|
||||
kim_query latconst split get_lattice_constant_hexagonal crystal=\["hcp"\] species=\["Zr"\] units=\["angstrom"\]
|
||||
variable a0 equal latconst_1
|
||||
variable c0 equal latconst_2
|
||||
variable c_to_a equal $\{c0\}/$\{a0\}
|
||||
lattice custom $\{a0\} a1 0.5 -0.866025 0 a2 0.5 0.866025 0 a3 0 0 $\{c_to_a\} &
|
||||
basis 0.333333 0.666666 0.25 basis 0.666666 0.333333 0.75
|
||||
... :pre
|
||||
|
||||
In this case the {kim_query} returns two arguments (since the hexagonal
|
||||
close packed (hcp) structure has two independent lattice constants).
|
||||
The default behavior of {kim_query} returns the result as a string
|
||||
with the values separated by commas. The optional keyword {split}
|
||||
separates the result values into individual variables of the form
|
||||
{prefix_I}, where {prefix} is set to the the {kim_query} {variable} argument
|
||||
and {I} ranges from 1 to the number of returned values. The number and order of
|
||||
the returned values is determined by the type of query performed.
|
||||
|
||||
[Define a crystal at finite temperature accounting for thermal expansion]
|
||||
|
||||
kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal
|
||||
boundary p p p
|
||||
kim_query a0 get_lattice_constant_cubic crystal=\["fcc"\] species=\["Al"\] units=\["angstrom"\]
|
||||
kim_query alpha get_linear_thermal_expansion_coefficient_cubic crystal=\["fcc"\] species=\["Al"\] units=\["1/K"\] temperature=\[293.15\] temperature_units=\["K"\]
|
||||
variable DeltaT equal 300
|
||||
lattice fcc $\{a0\}*$\{alpha\}*$\{DeltaT\}
|
||||
... :pre
|
||||
|
||||
As in the previous example, the equilibrium lattice constant is obtained
|
||||
for the Ercolessi and Adams (1994) potential. However, in this case the
|
||||
crystal is scaled to the appropriate lattice constant at room temperature
|
||||
(293.15 K) by using the linear thermal expansion constant predicted by the
|
||||
potential.
|
||||
|
||||
NOTE: When passing numerical values as arguments (as in the case
|
||||
of the temperature in the above example) it is also possible to pass a
|
||||
tolerance indicating how close to the value is considered a match.
|
||||
If no tolerance is passed a default value is used. If multiple results
|
||||
are returned (indicating that the tolerance is too large), {kim_query}
|
||||
will return an error. See the
|
||||
"query documentation"_https://openkim.org/doc/repository/kim-query
|
||||
to see which numerical arguments and tolerances are available for a
|
||||
given {query function}.
|
||||
|
||||
[Compute defect formation energy]
|
||||
|
||||
kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal
|
||||
...
|
||||
... Build fcc crystal containing some defect and compute the total energy
|
||||
... which is stored in the variable {Etot}
|
||||
...
|
||||
kim_query Ec get_cohesive_energy_cubic crystal=\["fcc"\] species=\["Al"\] units=\["eV"\]
|
||||
variable Eform equal $\{Etot\} - count(all)*$\{Ec\}
|
||||
... :pre
|
||||
|
||||
The defect formation energy {Eform} is computed by subtracting from {Etot} the
|
||||
ideal fcc cohesive energy of the atoms in the system obtained from
|
||||
"OpenKIM"_https://openkim.org for the Ercolessi and Adams (1994) potential.
|
||||
|
||||
NOTE: {kim_query} commands return results archived in
|
||||
"OpenKIM"_https://openkim.org. These results are obtained
|
||||
using programs for computing material properties
|
||||
(KIM Tests and KIM Test Drivers) that were contributed to OpenKIM.
|
||||
In order to give credit to Test developers, the number of times results
|
||||
from these programs are queried is tracked. No other information about
|
||||
the nature of the query or its source is recorded.
|
||||
|
||||
|
||||
Citation of OpenKIM IMs :h4
|
||||
|
||||
When publishing results obtained using OpenKIM IMs researchers are requested
|
||||
to cite the OpenKIM project "(Tadmor)"_#kim-mainpaper, KIM API
|
||||
"(Elliott)"_#kim-api, and the specific IM codes used in the simulations,
|
||||
in addition to the relevant scientific references for the IM.
|
||||
The citation format for an IM is displayed on its page on
|
||||
"OpenKIM"_https://openkim.org along with the corresponding BibTex file,
|
||||
and is automatically added to the LAMMPS {log.cite} file.
|
||||
|
||||
Citing the IM software (KIM infrastructure and specific PM or SM codes)
|
||||
used in the simulation gives credit to the researchers who developed them
|
||||
and enables open source efforts like OpenKIM to function.
|
||||
|
||||
|
||||
[Restrictions:]
|
||||
|
||||
The set of {kim_commands} is part of the KIM package. It is only enabled if
|
||||
LAMMPS is built with that package. A requirement for the KIM package,
|
||||
is the KIM API library that must be downloaded from the
|
||||
"OpenKIM website"_https://openkim.org/kim-api/ and installed before
|
||||
LAMMPS is compiled. When installing LAMMPS from binary, the kim-api package
|
||||
is a dependency that is automatically downloaded and installed. See the KIM
|
||||
section of the "Packages details"_Packages_details.html for details.
|
||||
|
||||
Furthermore, when using {kim_commands} to run KIM SMs, any packages required
|
||||
by the native potential being used or other commands or fixes that it invokes
|
||||
must be installed.
|
||||
|
||||
[Related commands:]
|
||||
|
||||
"pair_style kim"_pair_kim.html
|
||||
|
||||
:line
|
||||
|
||||
:link(kim-mainpaper)
|
||||
[(Tadmor)] Tadmor, Elliott, Sethna, Miller and Becker, JOM, 63, 17 (2011).
|
||||
doi: "https://doi.org/10.1007/s11837-011-0102-6"_https://doi.org/10.1007/s11837-011-0102-6
|
||||
|
||||
:link(kim-api)
|
||||
[(Elliott)] Elliott, Tadmor and Bernstein, "https://openkim.org/kim-api"_https://openkim.org/kim-api (2011)
|
||||
doi: "https://doi.org/10.25950/FF8F563A"_https://doi.org/10.25950/FF8F563A
|
||||
@ -1,46 +0,0 @@
|
||||
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
|
||||
|
||||
:link(lws,http://lammps.sandia.gov)
|
||||
:link(ld,Manual.html)
|
||||
:link(lc,Commands_all.html)
|
||||
|
||||
:line
|
||||
|
||||
kim_query command :h3
|
||||
|
||||
[Syntax:]
|
||||
|
||||
kim_query variable query_function web_query_flags :pre
|
||||
|
||||
variable = name of a (string style) variable where the result of the query is stored
|
||||
query_function = name of the OpenKIM web API query function to be used
|
||||
web_query_flags = a series of keyword=value pairs that represent the web query; supported keywords depend on query function :ul
|
||||
|
||||
[Examples:]
|
||||
|
||||
kim_query latconst get_test_result test=TE_156715955670 model=MO_800509458712 &
|
||||
prop=structure-cubic-crystal-npt species=\["Al"\] keys=\["a"\] units=\["angstrom"\] :pre
|
||||
|
||||
[Description:]
|
||||
|
||||
The kim_query command allows to retrieve properties from the OpenKIM
|
||||
through a web query. The result is stored in a string style
|
||||
"variable"_variable.html, the name of which must be given as the first
|
||||
argument of the kim_query command. The second required argument is the
|
||||
name of the actual query function (e.g. {get_test_result}). All following
|
||||
arguments are parameters handed over to the web query in the format
|
||||
{keyword=value}. The list of supported keywords and the type of how
|
||||
the value has to be encoded depends on the query function used. This
|
||||
mirrors the functionality available on the OpenKIM webpage at
|
||||
"https://query.openkim.org"_https://query.openkim.org/
|
||||
|
||||
[Restrictions:]
|
||||
|
||||
This command is part of the KIM package. It is only enabled if
|
||||
LAMMPS was built with that package. Furthermore, its correct
|
||||
functioning depends on compiling LAMMPS with libcurl support.
|
||||
See the "Build package"_Build_package.html doc page for more info.
|
||||
|
||||
[Related commands:]
|
||||
|
||||
"pair_style kim"_pair_kim.html, "variable"_variable.html
|
||||
@ -42,6 +42,7 @@ Commands_compute.html
|
||||
Commands_pair.html
|
||||
Commands_bond.html
|
||||
Commands_kspace.html
|
||||
Commands_removed.html
|
||||
Packages.html
|
||||
Packages_standard.html
|
||||
Packages_user.html
|
||||
@ -167,7 +168,7 @@ if.html
|
||||
include.html
|
||||
info.html
|
||||
jump.html
|
||||
kim_query.html
|
||||
kim_commands.html
|
||||
label.html
|
||||
lattice.html
|
||||
log.html
|
||||
|
||||
@ -42,16 +42,17 @@ the ADP potential files themselves. Likewise, the ADP potential files
|
||||
list atomic masses; thus you do not need to use the "mass"_mass.html
|
||||
command to specify them.
|
||||
|
||||
The NIST WWW site distributes and documents ADP potentials:
|
||||
[ADP potentials are available from:]
|
||||
|
||||
http://www.ctcms.nist.gov/potentials :pre
|
||||
The NIST WWW site at http://www.ctcms.nist.gov/potentials.
|
||||
Note that ADP potentials obtained from NIST must be converted
|
||||
into the extended DYNAMO {setfl} format discussed below.
|
||||
:l
|
||||
|
||||
Note that these must be converted into the extended DYNAMO {setfl}
|
||||
format discussed below.
|
||||
|
||||
The NIST site is maintained by Chandler Becker (cbecker at nist.gov)
|
||||
who is good resource for info on interatomic potentials and file
|
||||
formats.
|
||||
The OpenKIM Project at https://openkim.org/browse/models/by-type provides
|
||||
ADP potentials that can be used directly in LAMMPS with the "kim_commands
|
||||
interface"_kim_commands.html.
|
||||
:l
|
||||
|
||||
:line
|
||||
|
||||
|
||||
@ -12,76 +12,72 @@ pair_style kim command :h3
|
||||
|
||||
pair_style kim model :pre
|
||||
|
||||
model = name of KIM model (potential)
|
||||
model = name of a KIM model (the KIM ID for models archived in OpenKIM)
|
||||
|
||||
[Examples:]
|
||||
|
||||
pair_style kim ex_model_Ar_P_LJ
|
||||
pair_coeff * * Ar Ar :pre
|
||||
pair_style kim SW_StillingerWeber_1985_Si__MO_405512056662_005
|
||||
pair_coeff * * Si :pre
|
||||
|
||||
[Description:]
|
||||
|
||||
This pair style is a wrapper on the "Knowledge Base for Interatomic
|
||||
This pair style is a wrapper on the "Open Knowledgebase of Interatomic
|
||||
Models (OpenKIM)"_https://openkim.org repository of interatomic
|
||||
potentials, so that they can be used by LAMMPS scripts.
|
||||
potentials to enable their use in LAMMPS scripts.
|
||||
|
||||
Note that in LAMMPS lingo, a KIM model driver is a pair style
|
||||
(e.g. EAM or Tersoff). A KIM model is a pair style for a particular
|
||||
element or alloy and set of parameters, e.g. EAM for Cu with a
|
||||
specific EAM potential file.
|
||||
The preferred interface for using interatomic models archived in
|
||||
OpenKIM is the "kim_commands interface"_kim_commands.html. That
|
||||
interface supports both "KIM Portable Models" (PMs) that conform to the
|
||||
KIM API Portable Model Interface (PMI) and can be used by any
|
||||
simulation code that conforms to the KIM API/PMI, and
|
||||
"KIM Simulator Models" that are natively implemented within a single
|
||||
simulation code (like LAMMPS) and can only be used with it.
|
||||
The {pair_style kim} command is limited to KIM PMs. It is
|
||||
used by the "kim_commands interface"_kim_commands.html as needed.
|
||||
|
||||
See the current list of "KIM model
|
||||
drivers"_https://openkim.org/browse/model-drivers/alphabetical.
|
||||
NOTE: Since {pair_style kim} is called by {kim_interactions} as needed,
|
||||
is not recommended to be directly used in input scripts.
|
||||
|
||||
See the current list of all "KIM
|
||||
models"_https://openkim.org/browse/models/by-model-drivers
|
||||
|
||||
To use this pair style, you must first download and install the KIM
|
||||
API library from the "OpenKIM website"_https://openkim.org. The KIM
|
||||
section of the "Packages details"_Packages_details.html doc page has
|
||||
instructions on how to do this with a simple make command, when
|
||||
building LAMMPS.
|
||||
|
||||
See the examples/kim dir for an input script that uses a KIM model
|
||||
(potential) for Lennard-Jones.
|
||||
|
||||
:line
|
||||
|
||||
The argument {model} 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.
|
||||
The argument {model} is the name of the KIM PM.
|
||||
For potentials archived in OpenKIM
|
||||
this is the extended KIM ID (see "kim_commands"_kim_commands.html
|
||||
for details). LAMMPS can invoke any KIM PM, however there can
|
||||
be incompatibilities (for example due to unit matching issues).
|
||||
In the event of an incompatibility, the code will terminate with
|
||||
an error message. Check both the LAMMPS and KIM log files for details.
|
||||
|
||||
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:
|
||||
Only a single {pair_coeff} command is used with the {kim} style, which
|
||||
specifies the mapping of LAMMPS atom types to the species supported by
|
||||
the KIM PM. 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 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:
|
||||
For example, consider a KIM PM that supports Si and C species.
|
||||
If the LAMMPS simulation has four atom types, where the first three are Si,
|
||||
and the fourth is C, the following {pair_coeff} command would be used:
|
||||
|
||||
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.
|
||||
The first two arguments must be * * so as to span all LAMMPS atom types.
|
||||
The first three Si arguments map LAMMPS atom types 1, 2, and 3 to Si as
|
||||
defined within KIM PM. The final C argument maps LAMMPS atom type 4 to C.
|
||||
|
||||
: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. The file kim.log should be generated in the same
|
||||
case it is also useful to check the {kim.log} file for additional error
|
||||
information. The file {kim.log} should be generated in the same
|
||||
directory where LAMMPS is running.
|
||||
|
||||
To download, build, and install the KIM library on your system, see
|
||||
the lib/kim/README file. Once you have done this and built LAMMPS
|
||||
the {lib/kim/README} file. Once you have done this and built LAMMPS
|
||||
with the KIM package installed you can run the example input scripts
|
||||
in examples/kim.
|
||||
in {examples/kim}.
|
||||
|
||||
:line
|
||||
|
||||
@ -103,15 +99,14 @@ This pair style can only be used via the {pair} keyword of the
|
||||
|
||||
[Restrictions:]
|
||||
|
||||
This pair style is part of the KIM package. It is only enabled if
|
||||
LAMMPS was built with that package. See the "Build
|
||||
package"_Build_package.html doc page for more info.
|
||||
This pair style is part of the KIM package. See details on
|
||||
restrictions in "kim_commands"_kim_commands.html.
|
||||
|
||||
This current version of pair_style kim is compatible with the
|
||||
kim-api package version 2.0.0 and higher.
|
||||
|
||||
[Related commands:]
|
||||
|
||||
"pair_coeff"_pair_coeff.html
|
||||
"pair_coeff"_pair_coeff.html, "kim_commands"_kim_commands.html
|
||||
|
||||
[Default:] none
|
||||
|
||||
Reference in New Issue
Block a user