KIM API V2
Guide for porting content from KIM API v1 to v2

Previous Section: Summary of Differences Between kim-api-v1 and kim-api-v2.

Version 2 of the KIM API constitutes a major rewrite with a simplified interface, best practice design, and new capabilities. For more details, see the Features of the KIM API package page.

Version 2 is NOT backward compatible and therefore requires significant modifications to existing code (Model Drivers, Models, Test Drivers, and Tests) to work. The purpose of this document is to provide step-by-step instructions on how to transition content from version 1 to 2.

A complete translation table of v1 and v2 identifier names is available on the Summary of Differences Between kim-api-v1 and kim-api-v2 page.

This page includes instructions for Porting Models and Model Drivers and for Porting Simulators.

Porting Models and Model Drivers

Model drivers and stand-alone models compatible with version 1 of the KIM API will need to be modified to conform to version 2. A step-by-step process for doing so is described below. (In what follows the generic term "model" will be used to refer to both Model Drivers and Models. The only difference between the two cases is that Model Drivers have these two additional functions: KIM::ModelDriverCreate::GetNumberOfParameterFiles() and KIM::ModelDriverCreate::GetParameterFileName().)

Step 0

Step 1

Step 2

Become familiar with v2 by reading the documentation, and reviewing the example Model Drivers and/or Models. (The examples are under "Files" in the documentation. The ex_model_Ar_P_MLJ_F03.F03 and ex_model_Ar_P_Morse_07C.c examples are the same codes found in the Guide for porting content from KIM API v1 to v2 examples used in these instructions.)

As you review the material, if you have any questions, post them to the OpenKIM Google Group forum by emailing openk.nosp@m.im@g.nosp@m.oogle.nosp@m.grou.nosp@m.ps.co.nosp@m.m or by visiting the group. This will help others with similar questions. Continue using the forum for support in the next steps.

Step 3

You are now ready to make the modifications to the code needed for it to be compatible with v2.

Start with the ModelDriverCreate or ModelCreate routine. Since KIM descriptor files no longer exist in v2, the information encoded in these files must be incorporated into this routine (and the ModelComputeArgumentsCreate routine described in the next step) to make it available to the API.

Step 4

Next you will implement the ModelComputeArgumentsCreate and ModelComputeArgumentsDestroy routines. The create routine registers the model's supported compute arguments and compute callbacks. The destroy routine allows the model to clean up the memory (if any) it stored at the compute-arguments object's model buffer pointer.

Step 5

Step 6

Step 7

Now the new model can be used with the v2 simulator and the output compared with the original output from Step 1.

$ cd v2-ex_test_Ar_fcc_cluster
$ printf ex_model_Ar_P_MLJ_F03 | ./ex_test_Ar_fcc_cluster
Please enter valid KIM Model name:
This is Test : ex_test_Ar_fcc_cluster
--------------------------------------------------------------------------------
Results for KIM Model : ex_model_Ar_P_MLJ_F03
Energy, Force Norm, Lattice Spacing
2.6568305947e+01, 1.2671877978e+01, 4.2080000000e+00
1.5269225751e+01, 7.9639127468e+00, 4.3395000000e+00
8.1940651929e+00, 4.9863838571e+00, 4.4710000000e+00
3.7947024307e+00, 3.0924620572e+00, 4.6025000000e+00
1.0980474405e+00, 1.8835116189e+00, 4.7340000000e+00
-5.1288233270e-01, 1.1111343811e+00, 4.8655000000e+00
-1.4321763817e+00, 6.1892128072e-01, 4.9970000000e+00
-1.9129769394e+00, 3.0756389059e-01, 5.1285000000e+00
-2.1185529279e+00, 1.1421905922e-01, 5.2600000000e+00
-2.1545585638e+00, 2.4987808283e-02, 5.3915000000e+00
-2.0893135757e+00, 8.1104969450e-02, 5.5230000000e+00
-1.9668026189e+00, 1.1844534144e-01, 5.6545000000e+00
-1.8151243558e+00, 1.3646818860e-01, 5.7860000000e+00
-1.6520140667e+00, 1.4203290937e-01, 5.9175000000e+00
-1.4884681605e+00, 1.3991074278e-01, 6.0490000000e+00
-1.3310358744e+00, 1.3327798308e-01, 6.1805000000e+00
$ printf ex_model_Ar_P_Morse_07C | ./ex_test_Ar_fcc_cluster
Please enter valid KIM Model name:
This is Test : ex_test_Ar_fcc_cluster
--------------------------------------------------------------------------------
Results for KIM Model : ex_model_Ar_P_Morse_07C
Energy, Force Norm, Lattice Spacing
1.4703219623e+01, 6.9678657557e+00, 4.2080000000e+00
8.2453550705e+00, 4.8650873812e+00, 4.3395000000e+00
3.7883556879e+00, 3.3409407134e+00, 4.4710000000e+00
7.7810749699e-01, 2.2399352517e+00, 4.6025000000e+00
-1.1944148939e+00, 1.4518130136e+00, 4.7340000000e+00
-2.4291941022e+00, 8.9239060716e-01, 4.8655000000e+00
-3.1445433206e+00, 5.0063786968e-01, 4.9970000000e+00
-3.4996095359e+00, 2.3199479279e-01, 5.1285000000e+00
-3.6112724693e+00, 6.3687021777e-02, 5.2600000000e+00
-3.5604853404e+00, 8.7536239707e-02, 5.3915000000e+00
-3.4059878193e+00, 1.5700051389e-01, 5.5230000000e+00
-3.1896247548e+00, 1.9909723852e-01, 5.6545000000e+00
-2.9407853637e+00, 2.1928061006e-01, 5.7860000000e+00
-2.6800661721e+00, 2.2574027063e-01, 5.9175000000e+00
-2.4197463013e+00, 2.2234487833e-01, 6.0490000000e+00
-2.1685167432e+00, 2.1265537489e-01, 6.1805000000e+00
$ cd ..

Porting Simulators

Step 0

Step 1

Step 2

See Step 2 for Models, above.

Step 3

You are now ready to make the modifications to the code needed to make it compatible with v2.

Step 4

Step 5

Next Seciton: Browse files.