LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

### pair_style kim command

Syntax:

    pair_style kim virialmode model

- virialmode = KIMvirial or LAMMPSvirial
- model = name of KIM model (potential)

Examples:

    pair_style kim KIMvirial model_Ar_P_Morse
    pair_coeff * * Ar Ar

Description:

This pair style is a wrapper on the Knowledge Base for Interatomic Models (KIM) 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 virialmode determines how the global virial is calculated. If KIMvirial is specified, the KIM model performs the global virial calculation. If LAMMPSvirial is specified, LAMMPS computes the global virial using its fdotr mechanism.

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.

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

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:

    pair_coeff * * Si Si Si C

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 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.

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.

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.

Consult the KIM documentation for further details on KIM specifics.

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

    tar xvfz openkim*tgz

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:

1. 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).

          (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:

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

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

              The `%' symbol represents the bash sell prompt and should not be
              typed.

          (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

              bash:
              % export KIM_INTEL="yes"

              tcsh:
              % setenv KIM_INTEL "yes"

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

              bash:
              % export KIM_SYSTEM32="yes"

              tchs:
              % setenv KIM_SYSTEM32 "yes"

          (d) Define variable for dynamic linking (recommended)

              bash:
              export KIM_DYNAMIC=yes

              tcsh:
              setenv KIM_DYNAMIC=yes

              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 executable 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.

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

          % cd $KIM_DIR
          % make examples
          % make

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

          make                -- compiles the API and all Models and Tests
          make all            -- same as `make'
          make examples       -- copy examples into the appropriate directories
                                 (no overwrite)
          make examples-force -- copy examples into the appropriate directories
                                 (overwrite)
          make openkim-api    -- compiles only the API
          make clean          -- will remove .o, .mod, .a, .so and executable files
          make examples-clean -- remove all examples from the MODEL_DRIVERs,
                                 MODELs, and TESTs directories.

3. Verify that the compilation was successful by running a Test.

          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:

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

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

4. Each Test (and Model) has its own make file for compiling and linking. If changes are made to the code, re-compile (from the $KIM_DIR directory).
5. In case of using a non-standard location for any of the directories KIM_API, TESTs, MODEL_DRIVERS, or MODELs one or more of the following environment variables must be set:

       KIM_API_DIR
       KIM_TESTS_DIR
       KIM_MODEL_DRIVERS_DIR
       KIM_MODELS_DIR

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

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

This pair style does not write its information to binary restart files, 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.

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

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 for more info.

This current version of pair_style kim is compatible with the openkim-api package version 1.1.0 and higher.

Related commands:

pair_coeff

Default: none