# Using KIM Models

Using interatomic potentials archived in openkim.org with a simulation code that supports KIM involves two steps that need to be performed once:

1. Install the KIM potentials library.
2. Build the simulation code with support for KIM enabled. See the documentation of the simulator of your choice for instructions.

Once the steps above are completed, KIM Portable Models (PMs) and compatible Simulator Models (SMs) can be used by providing the KIM model identifier (KIM ID) in the simulation code's input file along with any other KIM-specific definitions required by the code. Examples for different simulators are provided below.

## ASE

In ASE, KIM PMs and KIM SMs compatible with Calculators supported by ASE are accessed using the `KIM Calculator`. The kim-query package provides an interface for performing queries. See the usage examples below (click to expand).

Cohesive energy calculation for fcc aluminum
``````#!/usr/bin/env python3
"""
Compute the cohesive energy and pressure of an FCC Al crystal using the
Ercolessi-Adams EAM potential implemented as a Portable Model (PM) in
OpenKIM for the experimental lattice constant a0=4.05 Angstrom.
"""
from ase.calculators.kim import KIM
from ase.lattice.cubic import FaceCenteredCubic
from ase.units import GPa

# Set up crystal and calculator
a0 = 4.05  # experimental lattice constant
atoms = FaceCenteredCubic("Al", latticeconstant=a0)
atoms.set_calculator(calc)

# Compute energy/pressure
ecoh = -atoms.get_potential_energy() / len(atoms)
stress = atoms.get_stress()
pressure_MPa = (-sum(stress[:3]) / 3.0) * 1e3 / GPa

print("Computed cohesive energy of {:.3f} eV/atom (experiment: 3.39 eV/atom)".format(ecoh))
print("Computed pressure of {} MPa".format(pressure_MPa))
``````
Cohesive energy calculation for fcc aluminum with query to openkim.org for lattice constant
``````#!/usr/bin/env python3
"""
Compute the cohesive energy and pressure of an FCC Al crystal using the
Ercolessi-Adams EAM potential implemented as a Portable Model (PM) in
OpenKIM for the equilibrium lattice constant obtained by querying openkim.org.
"""
from ase.calculators.kim import KIM
from ase.lattice.cubic import FaceCenteredCubic
from ase.units import GPa
from kim_query import get_lattice_constant_cubic

# Perform query to get lattice constant for this model
a0 = get_lattice_constant_cubic([model], ["fcc"], ["Al"], ["angstrom"])

# Set up crystal and calculator
atoms = FaceCenteredCubic("Al", latticeconstant=a0)
calc = KIM(model)
atoms.set_calculator(calc)

# Compute energy/pressure
ecoh = -atoms.get_potential_energy() / len(atoms)
stress = atoms.get_stress()
pressure_MPa = (-sum(stress[:3]) / 3.0) * 1e3 / GPa

print("Computed cohesive energy of {:.3f} eV/atom (experiment: 3.39 eV/atom)".format(ecoh))
print("Computed pressure of {} MPa".format(pressure_MPa))
``````

For a detailed explanation of using KIM models with ASE, see the KIM documentation in ASE.

## GULP

In GULP, once the code has been compiled with OpenKIM as an option, using a KIM PM simply involves specifying the model(s) to be used. See the usage examples below (click to expand).

Constant volume calculation for fcc Argon
``````grad conv
cell
5.26 5.26 5.26 90 90 90
frac
Ar   0.0  0.0  0.0
Ar   0.0  0.5  0.5
Ar   0.5  0.0  0.5
Ar   0.5  0.5  0.0

kim_model
ex_model_Ar_P_LJ

dump every kim1.res
``````
Constant pressure calculation for fcc Argon using two potentials
``````opti conp prop
cell
5.26 5.26 5.26 90 90 90
frac
Ar   0.0  0.0  0.0
Ar   0.0  0.5  0.5
Ar   0.5  0.0  0.5
Ar   0.5  0.5  0.0

kim_model 2
ex_model_Ar_P_LJ
ex_model_Ar_SLJ_MultiCutoff

dump every kim_2model.res
``````

For a detailed explanation of using KIM models with GULP, see the KIM documentation in GULP.

## LAMMPS

In LAMMPS, the standard potential specification commands (`pair_style`, `pair_coeff`, `bond_style`, etc.) are replaced with two KIM commands: `kim_init` at the start of input script to specify the KIM model and initialize it and the unit system, and `kim_interactions` command to define the species to atom type mapping. Additional commands for performing queries (`kim_query`) and accessing and changing KIM PM parameters (`kim_param`) are provided. See the usage examples below (click to expand).

Cohesive energy calculation for diamond silicon
``````# Generate a periodic diamond crystal and minimize the energy to obtain the
# equilibrium lattice constant and cohesive energy using the Stillinger-Weber
# potential implemented as a Portable Model (PM) in OpenKIM.

kim_init         SW_StillingerWeber_1985_Si__MO_405512056662_005 metal
boundary         p p p

# Define lattice, simulation box and crystal
lattice          diamond 5.4307
region           simbox block 0 1 0 1 0 1 units lattice
create_box       1 simbox
create_atoms     1 box

# Define atom-type-to-species-mapping
kim_interactions Si
mass             1 28.0855

# Minimize energy to obtain relaxed configuration
fix              1 all box/relax iso 0.0 vmax 0.001
min_style        cg
minimize         1e-25 1e-25 5000 10000

# Compute equilibrium lattice constant and cohesive energy and print out
variable         natoms equal count(all)
variable         aeq equal vol^(1/3)
variable         Ec equal pe/v_natoms
print            "Equilibrium lattice constant (Angstrom) = \${aeq}"
print            "Cohesive energy (eV) = \${Ec}"
``````
Cohesive energy calculation for diamond silicon with query to openkim.org for lattice constant
``````# Generate a periodic diamond crystal and compute cohesive energy using the
# Stillinger-Weber potential implemented as a Portable Model (PM) in OpenKIM
# for the equilibrium lattice constant for the specified potential obtained
# by querying openkim.org.

kim_init         SW_StillingerWeber_1985_Si__MO_405512056662_005 metal
boundary         p p p

# Define lattice, simulation box and crystal
kim_query        a0 get_lattice_constant_cubic crystal=["diamond"] species=["Si"] units=["angstrom"]
lattice          diamond \${a0}
region           simbox block 0 1 0 1 0 1 units lattice
create_box       1 simbox
create_atoms     1 box

# Define atom-type-to-species-mapping
kim_interactions Si
mass             1 28.0855

# Compute energy (No need to perform minimization, since equilibrium
# lattice constant from openkim.org is used)
run              0

# Compute cohesive energy and print out
variable         natoms equal count(all)
variable         Ec equal pe/v_natoms
print            "Equilibrium lattice constant (Angstrom) = \${a0}"
print            "Cohesive energy (eV) = \${Ec}"
``````
Cohesive energy calculation for fcc Aluminum with unit conversion enabled
``````# Generate a periodic fcc crystal and compute cohesive energy using the
# Pascuet-Fernandez MEAM potential implemented as a Simulator Model (SM) in OpenKIM.
#
# This script has unit conversion enabled, which means that it will work unchanged
# for any KIM model specified on the `kim_init` line regardless of the units system
# of the potential.

kim_init         Sim_LAMMPS_MEAM_PascuetFernandez_2015_Al__SM_811588957187_000 si unit_conversion_mode
boundary         p p p
lattice          fcc 4.05e-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"
``````
Cohesive energy calculation for diamond Si (loop over several KIM models with query and unit conversion)
``````# Loop over several KIM models for Si (names stored in MODEL index variable)
# and compute the cohesive energy for the diamond structure. For each potential,
# obtain the equilibrium lattice constant by querying openkim.org.
# Unit conversion is enabled, so this script will work for all potentials
# regardless of their unit system.
variable         MODEL index "SW_StillingerWeber_1985_Si__MO_405512056662_005"       &
"SW_LeeHwang_2012GGA_Si__MO_040570764911_000"           &
"Sim_LAMMPS_GW_GaoWeber_2002_SiC__SM_606253546840_000"
label            main_loop
clear

kim_init         \${MODEL} metal unit_conversion_mode
boundary         p p p

# Define lattice, simulation box and crystal
kim_query        a0_A get_lattice_constant_cubic crystal=["diamond"] &
species=["Si"]      &
units=["angstrom"]
variable         a0 equal \${a0_A}*\${_u_distance}  # Convert to unit system specied in kim_init line
lattice          diamond \${a0}
region           simbox block 0 1 0 1 0 1 units lattice
create_box       1 simbox
create_atoms     1 box

# Define atom-type-to-species-mapping
kim_interactions Si
mass             1 28.0855

# Compute energy (No need to perform minimization, since equilibrium
# lattice constant from openkim.org is used)
run              0

# Compute cohesive energy and print out
variable         natoms equal count(all)
variable         Ec equal pe/v_natoms
print            "Potential: \${MODEL}"
print            "Equilibrium lattice constant (Angstrom) = \${a0}"
print            "Cohesive energy (eV) = \${Ec}"

next MODEL
jump SELF main_loop

print "All simulations complete"
``````

For a detailed explanation of using KIM models with LAMMPS, see the KIM documentation in LAMMPS.