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 API and any models you wish to use.
  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.

Jump to [ASE] [DL_POLY] [GULP] [LAMMPS] [Python]

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)
calc = KIM("EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005")
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

model = "EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005"

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

# 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))
Cohesive energy calculation for fcc aluminum (loop over all Al potentials in openkim.org)
#!/usr/bin/env python3
"""
Compute the cohesive energy of an FCC Al crystal using all interatomic potentials for Al archived in openkim.org.
"""
from ase.calculators.kim import KIM
from kim_query import get_lattice_constant_cubic, get_available_models
from ase.lattice.cubic import FaceCenteredCubic

print("{:11s}  {}".format("Ecoh [eV]  ", "KIM Potential"))

# Query openkim.org to get list of all interatomic potentials for Al
models = get_available_models(species=["Al"], potential_type=["any"])

# Loop over all potentials
for model in models:

    try:
        # Setup calculator
        calc = KIM(model)

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

        # Build crystal and attach calculator
        atoms = FaceCenteredCubic("Al", latticeconstant=a0)
        atoms.calc = calc

        # Compute  and print energy
        ecoh = -atoms.get_potential_energy() / len(atoms)
        print("{:11.3f}  {}".format(ecoh, model))

        # Clear calculator
        calc.__del__()

    except:
        print("{:11s}  {}".format("unavailable", model))


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

DL_POLY

Performing a DL-POLY simulation requires at least three input data files, which must be provided in the working directory (Chapter 9, DL_POLY user manual).

  1. CONTROL file indicating the simulation conditions, amount of data to gather, run duration.
  2. CONFIG file containing atom positions, velocities and forces.
  3. FIELD file specifying the atomic properties (such as charge and mass), molecular stoichiometry, intermolecular topology and interactions, and molecular interactions and external fields. When DL-POLY is cross-compiled with OpenKIM functionality (Section 2.10, DL_POLY User Manual), it is possible to specify a complete intermolecular interaction model by providing an KIM model name.

Two keywords are employed when using KIM Models, one to select the potential and perform necessary initialization (kim_init). The other (kim_interactions) to define a mapping between atom types in DL-POLY to the available species in the KIM Model.

NVE Simulation of bcc Mo — CONTROL
A spectral neighbor analysis potential for Mo - Chi Chen (2019)

temperature         300.0      K

ensemble            nve
timestep            0.0005   ps

steps               1000        steps
equilibration       100        steps

no electrostatics
cutoff              4.615858 Angstroms

print               10        steps
stack               10        steps
stats               10        steps

job time            1000.0     s
close time          100.0      s

finish
NVE Simulation of bcc Mo — CONFIG
Lattice file generated by LAMMPS
1         3        128
12.6400000000        0.0000000000        0.0000000000
 0.0000000000       12.6400000000        0.0000000000
 0.0000000000        0.0000000000       12.6400000000
Mo    1
   -4.71188230359096     -4.75575122695536     -4.73706773932119
    0.909184561960046    -0.911633601971198     -1.18394499402636
Mo    2
   -1.47659029821887     -4.78710280161084     -4.66450346579229
    1.40257670738354     0.324903978252145     0.310910312585779
Mo    3
    1.59529849188042     -4.76413428974801     -4.68803519194302
    0.660740740601727    -0.491866171282581    -0.359652529936625
Mo    4
    3.17347499514037     -6.30855038252258     -3.16957513933369
    0.0307092705749136      2.26665892129071     -0.71899335350451
Mo    5
    4.7122359290169     -4.68289123104297     -4.75765173519036
    1.04419572314551    0.0387711369822811     -1.08805860122104
Mo    6
   -4.76092339023723     -1.54402300852523     -4.68928184475932
   -0.443180801305226     0.509018961396795     -1.66788516025644
Mo    7
   -3.13229751182997     -0.10411887201947     -3.17580759862311
    0.635668523249472    -0.240411254012082    -0.577211981679453
Mo    8
   -1.58086321095568     -1.58285589502458      -4.7422557672713
   -0.357690747617846      0.25669733060421     0.617595760975782
Mo    9
    0.0351647679739404     -3.18933514928466     -6.29281148535358
   -0.653315297234561     0.199575592109548     0.320853304205835
Mo    10
    3.14843738358104     -3.15344548216586     -6.31150955761059
   -1.25017182838304      1.03211067552798     0.123023190695775
Mo    11
    1.53629396521627     -1.59902226801215     -4.71654425859954
   -0.197262585162066    -0.179087604859979     -1.16290325816726
Mo    12
    6.339015405519     -3.07678940804521     -6.31767678962001
    1.10864723359579      2.15193632474106   -0.0959974524423881
Mo    13
    6.3108582211134     -3.17365642157343     -3.10846596865711
   -0.609087271043699     -1.44128742260101   -0.0185863311793461
Mo    14
    3.21542329956089     -3.15484356300777      -3.1428143279364
    0.487038786657437      1.43762686773518    -0.390404390846732
Mo    15
    4.7607814544776     -1.58362942180814     -4.73988208654335
   -1.37823449265722    -0.290592315870124      1.44278372806336
Mo    16
   -4.69471267994653      1.62094774561263     -4.69957850133161
   -0.329681586805883    -0.622075607210028    -0.801237388461878
Mo    17
   -6.35163176308963      3.12471658840276     -3.16436004389918
    0.714787249864181    -0.368993059676081      -2.7563476625241
Mo    18
   -0.0407616489807801    0.0138040315560399     -3.19540708451214
    1.46750219335779    -0.227007457600027     0.736596104653354
Mo    19
   -1.62809936850047      1.58773097184499     -4.71362754232991
   -1.54784307691126     -1.43009962644749    0.0640208218841111
Mo    20
    3.11591046348751    0.0908144408500604     -3.21402450618932
    0.784954636538742      2.12469800973577    -0.570633106210628
Mo    21
    1.5597583276004      1.58592089740086     -4.70228735288359
    0.80835609262232    -0.116319721899417     0.202717295007001
Mo    22
    0.0117087726076699      3.15117721395473     -6.26658844610754
    0.538167875243129       1.7181786158573    -0.306459680353483
Mo    23
    0.00505783039051977      3.13284277145039     -3.12853627227541
    0.476953814414847     0.783900984743369    0.0815205013603149
Mo    24
    4.7618598693353      1.59495301134788      -4.7889007950619
    0.0787540816888126    -0.546647160241456     0.662220245748077
Mo    25
    3.1254823673801      3.13370882169598     -3.15881776604428
   -1.19792428058315    -0.407892620086427      -1.0084190699384
Mo    26
   -6.28567852645275       6.2328563143947     -3.16240227791804
    0.83162019680847     -1.09324707561127   -0.0916573681254365
Mo    27
   -4.69116490259304       4.6891394671111     -4.72533271792378
   -1.09845105392441     -1.23138021354209      1.47096010494411
Mo    28
   -3.0967041295049       6.2177938336578     -6.34793228241801
    1.36747606074002     0.628407284367073      1.07011517489717
Mo    29
   -3.1132074117976       6.2888631795803     -3.17141712821215
   -0.129304379369042   -0.0817062228803556    -0.272795787471902
Mo    30
   -1.56865355187716       4.7361337115363     -4.73185994562256
   -0.322519420992548    -0.637944925891695      1.83770973440874
Mo    31
    0.0998335018291696       6.2812507387174      -6.3031504279017
   -0.26146849446095   -0.0772264231024576     0.263873962749878
Mo    32
    1.54776879555801       4.8252181903123     -4.76930302919852
   -0.0336630258954886      1.44429478024937    -0.209747243143173
Mo    33
    4.7503759178064       4.7300258335553     -4.83155328472992
    1.43990674101899    -0.581705226856733     0.785410366780032
Mo    34
   -3.12720692503661     -3.25115335882211     -3.17859317627199
    0.190241435985931     0.364594904080066     -1.14231481314388
Mo    35
   -4.71185208240622     -4.73412574872098     -1.57742379431427
   -0.704158877470746     0.248162779080477    -0.101879985275564
Mo    36
   -3.1872921418482      -6.3259884654834   -0.0335183536467696
    0.227537723542858    -0.990930825716333     0.578040334939198
Mo    37
   -3.17059318118968     -3.18643799523812    0.0484197075899599
   -0.434458511743445     0.670989919372586    0.0289694019323823
Mo    38
   -1.55989816167196     -4.77609462941707     -1.46388201787128
   -0.278648208912176    -0.586304276427283    -0.864052858604423
Mo    39
    0.0839065830364403     -6.33009838850413      -3.1559290063938
   -1.19031128122665     0.891821143793158    -0.934780583292259
Mo    40
   -0.00294434404522992     -3.20648312843294     -3.13697462236056
   -0.833750225457234     0.683229141617948     0.802765145105135
Mo    41
    1.62664287772017     -4.66896948400644     -1.58448786183896
   -0.400672511555206      2.72333186324668     0.090035647996254
Mo    42
    6.3396119884211      -6.2704213990325   -0.0115397121678802
    1.05099867360452    -0.222156271636295     0.144053084825375
Mo    43
    4.7025808873771     -4.75400914655492     -1.57840248390257
   -0.641981023289141     0.174617923668546      1.56693667967896
Mo    44
   -6.32437103065843  -0.000985511053359645     -3.12649626168141
    1.41492830459537    -0.157420149625791       1.2948833818415
Mo    45
   -4.7492772768786     -1.54014056529014     -1.57322606689212
    0.289207956584516     -1.04077362656625   -0.0546958019088486
Mo    46
   -1.59394511225425     -1.61889158644975     -1.54155570968496
    0.00713201895768442     0.200540665850895      -1.0903289223641
Mo    47
   -0.00921223784379954    0.0162915750526604   -0.0748527697794996
    0.443973498486471    -0.204579426608923     -0.38990731655192
Mo    48
    1.57194222485641     -1.51068553348786     -1.55866050761202
   -0.236464193699661    -0.683774882046722     -1.02370664067852
Mo    49
    4.7882836378726     -1.56818017326724     -1.56801871407483
    1.2125552190851      1.44130327812632      1.31407564745414
Mo    50
    3.17976622169574     -0.04420561183532    0.0583711004127903
    0.271042087782537     -1.25742826714692    -0.161934580765679
Mo    51
   -4.72622154720761      1.60114541352462     -1.56942216313709
   -1.10655524049115     -1.74591142556949      1.12473434110016
Mo    52
   -3.13232872441934      3.11544378637648     -3.08654590511844
    0.243470593889031     -2.05730994706083      1.42839542818612
Mo    53
   -1.58430847389268      1.60449808842519      -1.5970420308698
   -1.0854517445895     0.949992723243148     -1.51538650982065
Mo    54
    1.56237872183771      1.50901636633108     -1.53702118385124
    0.129912269864519     -1.02727450758822     -1.29841695193667
Mo    55
    3.1320382372402      3.16144203508849    0.0123391029394302
   -0.181346160385745     -1.17271230053804    -0.800099692550845
Mo    56
    4.7306439771022      1.61675635825846     -1.60531361376109
    0.827606137875512     -1.19603765339063       1.2509031386211
Mo    57
   -4.70846380991017       4.7484449901903     -1.62748647371299
    0.0693524886694426      -1.2602689479037    -0.454179969728633
Mo    58
   -6.38304169623968      3.24046335199573  -0.00210576284352015
    1.29625249347357     0.146707463463349      0.35226255379096
Mo    59
   -1.58090830046317       4.7847334332904     -1.54900381152967
    1.69894905588054      1.39225329555867    -0.115087099897976
Mo    60
    1.53344747227343       4.6784575769395     -1.52720812034997
   -1.30184203774278     -2.20871420579743    -0.715826812340338
Mo    61
    4.717740050367       4.7314798198006     -1.68081471367408
   -0.133934436235894     0.928559112628883     0.180603484375731
Mo    62
   -4.73245145384803     -4.74805302952217      1.63258788900539
   -0.082046694683921     0.926549534323232       1.4300942657775
Mo    63
   -0.00296507221364983     -6.33385158476168    0.0458429695107698
   -1.15901138952727     -2.04669885312821     0.738323289291966
Mo    64
   -1.58668605382643     -4.79093330990793      1.56543512480374
    1.40391217835338      -1.5511352996125     0.147809991641935
Mo    65
    1.56638789534719     -4.77111394233469       1.5810455493783
    0.620463136637079    -0.546337910344174    -0.667038464982166
Mo    66
    3.13940293347141     -6.26359463203024   -0.0234580116502796
    0.75538061750163    -0.067510412676398     -1.59313723781539
Mo    67
    4.7717614483131     -4.73997503463079      1.62989513463502
    1.03864638088717      1.61839289566559      1.41928578917738
Mo    68
    3.11010810679174     -6.27385774285175      3.23054197343538
   -0.401075516518561    -0.624954273247701     -1.41296086754438
Mo    69
   -6.31776449804599     -3.15725322179785   0.00471316774367025
    0.110517075337587      1.26433191031523     0.540283986256564
Mo    70
   -6.31744628949036   0.00604307328664966    0.0258416389793803
   -0.357596437759434     0.798432146900684     -2.39560507050455
Mo    71
   -4.7749304269219     -1.60586009256426      1.58370163863756
   -0.746216179500628     0.614120019772225     0.103485567169495
Mo    72
   -3.19537373987329    0.0494489144308403      3.16670882458953
   -1.84911175301177    -0.573787456724822   -0.0950950086371485
Mo    73
   -1.61497124851074     -1.69219959590162      1.58864053334419
   -0.0415113763884795      0.43963786937618    -0.233780890047983
Mo    74
    0.09550253238758     -3.14513379801183    0.0173703185981697
    1.14941184492922    -0.120367103735217     0.483844312402925
Mo    75
    1.58759784757206     -1.59328206583596      1.55339369974036
    1.30518406926078      1.30822273732194     0.416863334446899
Mo    76
    0.0321467957279999    0.0580821079529201      3.14367916360323
    1.51048764661082   -0.0157209977401297     0.718524035930941
Mo    77
    3.11036960219303    0.0320896236831603      3.02932592629113
    1.48960252322349     -1.62518518866947     -0.89705342726576
Mo    78
    3.2111548758187     -3.11332630773321      0.02047306451471
    1.4456201516023    -0.422118803000761       0.0306370687738
Mo    79
    4.7641653468433     -1.65769193677087      1.61264100539581
   -1.48818834250653     -1.29219072641552    -0.248044692308605
Mo    80
   -3.2368954339046     -0.01302162775659    0.0186407355466303
   -0.837333917945347     0.327536944433001    -0.994989534845457
Mo    81
   -3.20615010195006       3.2241518587283   -0.0428246741405598
    0.567700486757723    -0.500751137584516    -0.476014851978143
Mo    82
   -4.75382332266472      1.61233293839179      1.58037847715954
   -0.675247898938658     0.391541913744124     0.258909589655307
Mo    83
   -6.36336877397989      3.23722147622073      3.05509891831119
    1.58523372387901    -0.557099262154301     0.829631423908636
Mo    84
   -3.16571200087332      3.20158400607567      3.16165930418443
    1.96029152638174    -0.244952122928444     0.479596458996372
Mo    85
   -0.10396141919859      3.14544947788064   -0.0203836052705997
    0.0261878923479138     -0.42446689924851      1.44502505356596
Mo    86
   -1.65046204422516      1.53687428393233      1.55528643750616
    0.660699454579558    -0.291232251096988    -0.789470093337626
Mo    87
    1.54274942138252      1.55069386236928      1.49377137206754
   -1.36581941963616     0.456052816760047   -0.0391186860751098
Mo    88
    4.737677575945      1.59056270512109      1.57496908886963
   -1.31466129126288   -0.0279982979274676    -0.841113373600737
Mo    89
    6.2988880293231    0.0368208568021702      3.12008914305459
    1.01372865882571    -0.673208615177751      1.02313095784061
Mo    90
   -4.73075606491019       4.7981813504156      1.53465865028129
   -0.249435152755958      1.59217553704807    -0.717652079099442
Mo    91
   -1.62018341488153       4.6835255745249      1.60682838367601
    0.493468953254355    -0.516590949359211      1.01064886479572
Mo    92
    1.55560277750743       4.7347324121915       1.5877498507937
    0.305560932379222    0.0331601624965584    -0.259798670506521
Mo    93
    4.6890713101492        4.825967998398      1.58004629267164
   -1.37321409168155      0.47142205926358     0.941778586242026
Mo    94
    3.1473481875615      3.22023151422407      3.11282846625787
    0.784929167522629    -0.399602542591604     0.445885989329219
Mo    95
   -6.27300180994132     -6.31811649020245       6.2810464306219
   -2.3916446903652      1.29251572579675   -0.0359104387141414
Mo    96
   -6.32826271537505     -6.22977445973828       3.1683489485287
    1.05830401875915     0.919614851819715    -0.194251107400867
Mo    97
   -4.7644429166643     -4.74245808908998       4.8105064203522
   -1.29511845391429    -0.426622448140538    -0.384798028362433
Mo    98
   -1.56739144052492     -4.73908155258096        4.797793872703
    0.769453114295312    -0.413112325392267     0.860406057288741
Mo    99
    0.0158096047096397     -3.12922448718049      3.18208970291699
   -0.835527569163069     0.464571491036554      1.30817756813937
Mo    100
    1.5731950067858     -4.74089876465131       4.7616834128534
   -1.56177056488161    -0.241847116049243     0.902045815200185
Mo    101
    3.22030447283098     -6.33048351894716        6.279879529258
    0.82511263451885     0.505949746213024    -0.434251678149376
Mo    102
    6.3164515590919     -3.17164241359962      3.24392383242706
   -0.0914033779955501      -1.3975421303865     0.196609503495178
Mo    103
    4.7533211826231     -4.70350047553872       4.7498565213472
    0.70728947145152    -0.732884290090325      2.06196446056374
Mo    104
    3.19507198194443     -3.16558378396847       3.1383460437082
    2.81709206814044     0.420199842312127     -1.11272871711718
Mo    105
   -3.13185839774854      -3.1990946173276       6.3536024261889
    1.18806208979067     0.689635675761072     0.797631903807296
Mo    106
   -4.7270489636797     -1.56833456045325        4.719239952647
   -0.229754174241757     0.280679406936728     -2.48446906174729
Mo    107
   -0.0216646558009499     -0.05702904116787       6.3295142617052
   -1.27336380921337     -1.13658772076091      0.34263365062584
Mo    108
   -3.12529934632222     -3.20434680186213      3.19073700013275
   -1.46032972223485    -0.122726262562069   -0.0489424751089928
Mo    109
   -1.59674388042757     -1.59974446101823       4.7772715655034
   -0.780670207468822     0.686752514021878     0.365800420580614
Mo    110
    1.60412266300703     -1.57231795124954       4.7450589924325
   -0.0841741499670551    -0.933526634757347    -0.330994905036137
Mo    111
    4.7052830287047     -1.56800846669313        4.787498390883
   -1.54514250126267      2.14874982997118     0.819689850229392
Mo    112
   -3.17742494528964      0.02341172812016       6.2647922749589
   -0.925548485636346     0.918192639126877     0.942326826522291
Mo    113
   -6.29404910917063      3.12033123008562       6.3538391190454
    0.304812699310844     0.786774924934911      1.05760834309614
Mo    114
   -3.13058925528951      3.14034796539758       6.2567434765124
    0.379661678247979    -0.354807461158354     0.199797881637866
Mo    115
   -4.76936738587883      1.60105657563815       4.6838309441159
   -1.9175833054121     -2.37802070082715       2.0550013828815
Mo    116
   -1.56987646012069      1.64208506806761       4.6889835809545
   -0.3863343008861     0.653321564955312     0.596235767715297
Mo    117
    0.00282946816288021      3.17899468253633      3.12138664702888
   -0.14413073595369    -0.861507771514397     0.259329816291733
Mo    118
    3.10902562719951      0.02691454333611        6.302468622122
   -1.28692213903008     0.432655831899221    -0.508739049884203
Mo    119
    1.61638510342819      1.61719719603882       4.7214429502253
   -0.68460743452509   -0.0647370088862147      1.26143085140901
Mo    120
    6.2839418536075   -0.0413693947839402       6.3193519262317
   -0.13521210062696    -0.766372676621283     -2.43221832213254
Mo    121
    4.786621430604      1.60164327657258       4.6371494134308
   -0.199873190105537    -0.517150446949775     0.157438293326773
Mo    122
   -4.7342630767826       4.7494542626056       4.7385113577704
   -1.27438188991241    -0.357671097388172     -1.01151615027623
Mo    123
   -3.14255581614057       6.3124051773942      3.15026560958508
    1.23039636921693     0.549128398220846    -0.501088375485027
Mo    124
   -0.0206671187571503       6.2923315506699      3.19858710891953
   -0.628039611607668       0.2908677885472     0.041749540072862
Mo    125
   -1.6018634658843       4.6881781867005       4.7726546544738
   -1.83729857922658      2.56080175627108    -0.513283065782085
Mo    126
    1.59109197259427       4.7681063750229       4.7517120277528
    0.72455232619666    -0.392000502504453     -0.73072716260215
Mo    127
    3.20422188988571      3.16346811464041       6.2701730342979
   -1.47051029660509     0.264330471651536     -2.22972451216549
Mo    128
    4.7719736918674        4.759186873696       4.6878907843546
    0.32702020955583     0.568543438397972      1.72144451996915
NVE Simulation of bcc Mo — FIELD
A spectral neighbor analysis potential for Mo - Chi Chen (2019)
units             ev
molecular         types    1
Molybdenum
nummols           128
atoms             1
Mo                95.94    0.0   1
finish
kim_init          SNAP_ChenDengTran_2017_Mo__MO_698578166685_000
kim_interactions  Mo
close


# A spectral neighbor analysis potential for Mo - Chi Chen (2019)
#
# This example requires that the KIM Portable Model (PM)
# SNAP_ChenDengTran_2017_Mo__MO_698578166685_000
# is installed.
#
# This can be done with the command:
# kim-api-collections-management install user SNAP_ChenDengTran_2017_Mo__MO_698578166685_000
#
# If this command does not work, you may need to setup your PATH to find the utility.
# If you installed the kim-api using the DL_POLY CMake build, you can do the following
# (where the current working directory is assumed to be the DL_POLY build directory)
# source ./int-kim-api/kim-api-build/bin/kim-api-activate
#
# Or, see https://openkim.org/doc/obtaining-models for alternative options.
#

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

Additionaly, you can watch the presentations on using OpenKIM in LAMMPS that were presented at the recent 2021 LAMMPS Workshop:

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.

# Initialize potential and indicate that values in the script are in
# LAMMPS `metal` units. KIM Portable Models will adapt to this unit system
# if they can or return an error. KIM Simlator Models cannot adapt, and
# so will return an error if they do not use `metal` units. (An example
# on how to use KIM provided unit converstion in LAMMPS is shown in a
# later example.)
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.

# Initialize potential and indicate that values in the script are in
# LAMMPS `metal` units. (See earlier example for explanation of unit
# handling for KIM potentials.)
kim_init         SW_StillingerWeber_1985_Si__MO_405512056662_005 metal
boundary         p p p

# Get diamond lattice constant for silicon in Angstrom units predicted
# by the potential defined in the `kim_init` line.
kim_query        a0 get_lattice_constant_cubic crystal=["diamond"] &
                                               species=["Si"]      &
                                               units=["angstrom"]

# Define lattice, simulation box and crystal
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.

# Initialize potential, indicate that values in the script are in LAMMPS `si` units,
# and request unit conversion factors from the potential's units to `si` units.
kim_init         Sim_LAMMPS_MEAM_PascuetFernandez_2015_Al__SM_811588957187_000 si unit_conversion_mode

# Define lattice, simulation box, and crystal
boundary         p p p
lattice          fcc $(4.05e-10*v__u_distance)  # convert from si distance (m)
                                                # to the potential's distance unit.
region           simbox block 0 1 0 1 0 1 units lattice
create_box       1 simbox
create_atoms     1 box
mass             1 $(4.480134e-26*v__u_mass)

# Define mapping from species to LAMMPS atom types
kim_interactions Al

# Compute cohesive energy. Convert back from the potential's units
# to LAMMPS `si` units (J for energy).
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"
Cohesive energy calculation for fcc Ni (loop over all interatomic potentials for Ni in openkim.org with unit conversion)
# Define species for which calculation will be performed
variable species index Ni

# Get all interatomic potentials in openkim.org for the specified species
# and place in the index variable `potential`.
kim_query potential index get_available_models species=[${species}]

# Loop over the potentials and compute cohesive energy
label loop
   log log.${potential}

   # Initialize potential, indicate that values in the script are in
   # LAMMPS `metal` units, and request unit conversion factors from the
   # potential's units to `metal` units
   kim init ${potential} metal unit_conversion_mode

   # Get fcc lattice constant predicted by potential for fcc of ${species} in Angstrom
   kim query a0_A get_lattice_constant_cubic crystal=[fcc] &
                                             species=[${species}] &
                                             units=[angstrom]

   # Convert the lattice constant from Angstrom to the distance units used
   # by the potential. (Conversion factor defined by the `kim_init` line.)
   variable a0 equal ${a0_A}*${_u_distance}

   # Create simulation box and atoms
   lattice fcc ${a0}
   region simbox block 0 1 0 1 0 1 units lattice
   create_box 1 simbox
   create_atoms 1 box
   mass         1 58.69340

   # Define mapping from species to LAMMPS atom types
   kim interactions ${species}

   # Compute cohesive energy. Convert back from the potential's units
   # to LAMMPS `metal` units (eV for energy).
   neigh_modify page 500000 one 10000
   run 0
   variable natoms equal count(all)
   variable ecoh equal pe/${natoms}/${_u_energy}
   print "${ecoh}  ${potential}"

   # Move on to next potential
   clear
   next potential
jump SELF loop
Energy calculation for a NiO rock-salt structure involving a change in periodicity that requires potential reinitialization
# Initialize potential and indicate that values in the script are in
# LAMMPS `metal` units. (See earlier example for explanation of unit
# handling for KIM potentials.)
kim_init Sim_LAMMPS_Buckingham_FisherMatsubara_2005_NiO__SM_337243826931_000 metal

# Define the rock salt (B1) NiO crystal structure
boundary p p p
lattice custom 4.16 &
        a1     1.0 0.0 0.0 &
        a2     0.0 1.0 0.0 &
        a3     0.0 0.0 1.0 &
        basis  0.0 0.0 0.0 &
        basis  0.5 0.0 0.0 &
        basis  0.0 0.5 0.5 &
        basis  0.5 0.5 0.5 &
        basis  0.5 0.0 0.5 &
        basis  0.0 0.0 0.5 &
        basis  0.5 0.5 0.0 &
        basis  0.0 0.5 0.0
region myreg block 0 1 0 1 0 1
create_box 2 myreg
create_atoms 1 box  &
        basis  2 2  &
        basis  4 2  &
        basis  6 2  &
        basis  8 2
mass 1 58.6934
mass 2 15.999

# Define mapping from species to LAMMPS atom types
kim_interactions Ni O

# Minimize energy with respect to box size to find equilibrium structure
fix 1 all box/relax iso 0.0
minimize 1e-6 1e-6 5000 10000

# Change the box to be aperiodic in the z direction and create a vacuum
# on both sides so as to create a single-unit-layer-thick slab
change_box all boundary p p f z final -20.0 20.0

# Always reissue kim_interactions after any changes to the simulation box
# (The change in periodicity requires changes to the `kspace` command that
# is part of the definition of Buckingham potentials. This is
# automatically managed by KIM for the Buckingham simulator model.)
kim_interactions Ni O

# Compute thermodynamic variables
run 0
Fitting a Lennard-Jones potential within the LAMMPS Python interface using the kim_param command
#!/usr/bin/env python3
from scipy.optimize import minimize
from lammps import lammps
from kim_query import get_lattice_constant_cubic

# Query openkim.org for the lattice constant predicted by referenced Lennard-Jones (LJ) potential
# for face-centered cubic (fcc) argon in Angstrom units.
LATTICE=get_lattice_constant_cubic(["LJ_Truncated_Nguyen_2005_Ar__MO_398194508715_001"], ["fcc"], ["Ar"], ["angstrom"])

# LAMMPS block to define periodic boundary conditions and initialize the LJ potential
# (used below)
START_BLOCK="""
boundary     p p p
atom_style   atomic
kim_init     LJ_Truncated_Nguyen_2005_Ar__MO_398194508715_001 metal
"""

# LAMMPS block to create the simulation box and define the species to atom type mapping
# (used below)
MID_BLOCK="""
region       box block 0 1 0 1 0 1 units lattice
create_box   1 box
create_atoms 1 box
mass         1 39.948
kim_interactions Ar
"""

# LAMMPS block to minimize energy with respect to the box size to find equilibrium state
# (used below)
END_BLOCK="""
neigh_modify delay 10 check yes page 100000
fix 1 all box/relax iso 0.0 vmax 0.001
thermo 10
min_style cg
minimize 1e-25 1e-25 5000 10000
"""

# Experimental value for the Cohesive Energy eV/atom
# http://www.knowledgedoor.com/2/elements_handbook/cohesive_energy.html
# The LJ potential will be refit to determine the value of the epsilon parameter
# that will give a cohesive energy equal to the experimental value.
EXP_CohesiveEnergy=-0.080


# The cost function for fitting the potential is the difference squared between
# the cohesive energy predicted by the potential and the experimental value.
# The fitting process aims to drive the cost to zero.
#
# The key command is the `kim_param` command. This sets the value of the epsilon
# parameter of the LJ potential to the value x[0] transferred into the `costfn` function.
def costfn(x):
    lmp = lammps()
    lmp.commands_string(START_BLOCK)
    lmp.command('lattice fcc {}'.format(LATTICE[0]))
    lmp.commands_string(MID_BLOCK)
    lmp.command('kim_param set epsilon 1 {}'.format(x[0]))
    try:
        lmp.commands_string(END_BLOCK)
    except:
        return 1e100
    natoms = lmp.get_natoms()
    pe = lmp.get_thermo("pe")
    CohesiveEnergy = pe/natoms
    cost = EXP_CohesiveEnergy - CohesiveEnergy
    return cost*cost

# Main code -- minimize the cost function (`costfn`) with respect to epsilon starting from
# an initial value of epsilon = 0.6e-2.
if __name__ == '__main__':
    res = minimize(costfn, [0.6e-2], method='BFGS', options={'disp': True, 'gtol': 1e-12})
    print(res.x)


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

Python

KIM potential can be accessed directly from Python code using the kimpy. The kimpy package is the Python interface to the KIM Application Programming Interface (API). See the usage examples below (click to expand).

Python script to compute dimer energy as a function of distance between atoms using a KIM potential
"""kimpy example"""

import numpy as np
import kimpy

# Callback routine for the KIM API to get atom neighbor lists
def get_neigh(data_in, cutoffs_in, neighbor_list_index_in, particle_number_in):
    neighbors = data_in['neighbors'][particle_number_in]
    return (neighbors, 0)

# Function to construct neighbor lists for the atoms.
# (This is a highly-inefficient N^2 algorithm that should only be used for
# small numbers of atoms.)
def create_neigh(coords_in, cutoff, neigh_in):
    n = coords_in.shape[0]
    neighbors = []
    for i in range(n):
        neigh_i = []
        for j in range(n):
            if j == i:
                continue
            dist = np.linalg.norm(coords_in[i] - coords_in[j])
            if dist < cutoff:
                neigh_i.append(j)
        neigh_i = np.array(neigh_i, dtype=np.intc)
        neighbors.append(neigh_i)
    neigh_in['cutoff'] = cutoff
    neigh_in['num_particles'] = n
    neigh_in['neighbors'] = neighbors

# Initialize KIM potential specifying the units requested from the potential.
modelname = 'EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005'
requestedUnitsAccepted, kim_model, _ = kimpy.model.create(
    kimpy.numbering.zeroBased,
    kimpy.length_unit.A,
    kimpy.energy_unit.eV,
    kimpy.charge_unit.e,
    kimpy.temperature_unit.K,
    kimpy.time_unit.ps,
    modelname)

# Define simulation arguments
N = 2
coords = np.zeros((N, 3), dtype=np.double)
forces = np.zeros((N, 3), dtype=np.double)
energy = np.array([0.0], dtype=np.double)
num_particles = np.array([N], dtype=np.intc)
species_code = np.zeros(num_particles, dtype=np.intc)
particle_contributing = np.zeros(num_particles, dtype=np.intc)

# Set KIM API pointers to simulation arguments
compute_arguments, _ = kim_model.compute_arguments_create()
compute_arguments.set_argument_pointer(
    kimpy.compute_argument_name.numberOfParticles,
    num_particles)
compute_arguments.set_argument_pointer(
    kimpy.compute_argument_name.particleSpeciesCodes,
    species_code)
compute_arguments.set_argument_pointer(
    kimpy.compute_argument_name.particleContributing,
    particle_contributing)
compute_arguments.set_argument_pointer(
    kimpy.compute_argument_name.coordinates, coords)
compute_arguments.set_argument_pointer(
    kimpy.compute_argument_name.partialEnergy, energy)
compute_arguments.set_argument_pointer(
    kimpy.compute_argument_name.partialForces, forces)

# Setup neighbor lists through KIM API callback mechanism
neigh = dict()
compute_arguments.set_callback(
    kimpy.compute_callback_name.GetNeighborList, get_neigh, neigh)

# Setup for calculation
influence_dist = kim_model.get_influence_distance()
_, code, _ = kim_model.get_species_support_and_code(kimpy.species_name.Al)
species_code[:] = code
particle_contributing[:] = 1

# Loop over dimer energy
for z in np.arange(1., np.ceil(influence_dist)+0.5, 0.5):
    coords[1, 2] = z
    create_neigh(coords, influence_dist, neigh)
    kim_model.compute(compute_arguments)
    print('{:18.10e} {:18.10e}'.format(z, energy[0]))

# Free allocated memory
kim_model.compute_arguments_destroy(compute_arguments)
kimpy.model.destroy(kim_model)


For a detailed explanation of the KIM API, see the KIM API documentation.