kim-api  2.3.0+v2.3.0.GNU.GNU.
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
Explaination of CMake Files for KIM API Items and Simulators

Previous Section: Implementation.

This section describes the content of CMake files necessary for the configuration and build of KIM API items (Model Drivers, Portable Models, and Simulator Models) as well as for Simulators. Details are also provided for Simulators that do not use the CMake build system.

Model Driver CMakeLists.txt files

Here is the CMakeLists.txt file for the example Model Driver ex_model_driver_P_LJ.

cmake_minimum_required(VERSION 3.10)
list(APPEND CMAKE_PREFIX_PATH $ENV{KIM_API_CMAKE_PREFIX_DIR})
find_package(KIM-API-ITEMS 2.2 REQUIRED CONFIG)
kim_api_items_setup_before_project(ITEM_TYPE "modelDriver")
project(ex_model_driver_P_LJ LANGUAGES Fortran)
kim_api_items_setup_after_project(ITEM_TYPE "modelDriver")
add_kim_api_model_driver_library(
NAME ${PROJECT_NAME}
CREATE_ROUTINE_NAME "model_driver_create_routine"
CREATE_ROUTINE_LANGUAGE "fortran"
)
target_sources(${PROJECT_NAME} PRIVATE ${PROJECT_NAME}.f90)

Let us go through this line by line to explain.

cmake_minimum_required(VERSION 3.10)

This line ensures that an appropriate version of CMake is being used.

list(APPEND CMAKE_PREFIX_PATH $ENV{KIM_API_CMAKE_PREFIX_DIR})
find_package(KIM-API-ITEMS 2.2 REQUIRED CONFIG)

These lines tell CMake to find the settings for building KIM API items with the KIM API library installed on the system.

kim_api_items_setup_before_project(ITEM_TYPE "modelDriver")

This line performs various setup necessary to configure and build a Model Driver item. (These settings must be performed before the project command on the next line.)

project(ex_model_driver_P_LJ LANGUAGES Fortran)

This line tells CMake to create a "project" with name equal to the item's name ex_model_driver_P_LJ and that the item will require a Fortran compiler to be built.

kim_api_items_setup_after_project(ITEM_TYPE "modelDriver")

This line performs various setup necessary to configure and build a Model Driver item. (These settings must be performed after the project command on the previous line.)

add_kim_api_model_driver_library(
NAME ${PROJECT_NAME}
CREATE_ROUTINE_NAME "model_driver_create_routine"
CREATE_ROUTINE_LANGUAGE "fortran"
)

These lines register the item with the KIM API CMake build system and provide necessary metadata. The NAME argument is required and here the CMake variable PROJECT_NAME, which was set as a result of the project command (above), is used to provide the name of the Model Driver item.

The CREATE_ROUTINE_NAME argument specifies the identifier used to define the KIM::ModelDriverCreate routine for the item. This argument is required.

The CREATE_ROUTINE_LANGUAGE argument specifies the programming language in which the create routine is written (valid values are: cpp, c, and fortran).

There is also an additional (optional) argument METADATA_FILES. This can be set to a space separated list of file names that should be included with the Model Driver item as metadata files. These metadata files will not be directly used by the KIM API in any way, but they may be accessed through the KIM::Collections interface.

target_sources(${PROJECT_NAME} PRIVATE ${PROJECT_NAME}.f90)

This line associates the item's source code files with its CMake "target", which is set to the value given for the NAME argument in the call to add_kim_api_model_driver_library. After the PRIVATE keyword a space separated list of source code file names can be given. This list of files should contain all source code (not header) files that are necessary to compile and build the Model Driver item. In this example there is just a single Fortran soruce file with the same name as the item.

Portable Model using a Model Driver CMakeLists.txt files

Here is the CMakeLists.txt file for the example Portable Model ex_model_Ar_P_Morse.

cmake_minimum_required(VERSION 3.10)
list(APPEND CMAKE_PREFIX_PATH $ENV{KIM_API_CMAKE_PREFIX_DIR})
find_package(KIM-API-ITEMS 2.2 REQUIRED CONFIG)
kim_api_items_setup_before_project(ITEM_TYPE "portableModel")
project(ex_model_Ar_P_Morse)
kim_api_items_setup_after_project(ITEM_TYPE "portableModel")
add_kim_api_model_library(
NAME ${PROJECT_NAME}
DRIVER_NAME "ex_model_driver_P_Morse"
PARAMETER_FILES "ex_model_Ar_P_Morse.params"
)

Let us go through this line by line to explain.

cmake_minimum_required(VERSION 3.10)

This line ensures that an appropriate version of CMake is being used.

list(APPEND CMAKE_PREFIX_PATH $ENV{KIM_API_CMAKE_PREFIX_DIR})
find_package(KIM-API-ITEMS 2.2 REQUIRED CONFIG)

These lines tell CMake to find the settings for building KIM API items with the KIM API library installed on the system.

kim_api_items_setup_before_project(ITEM_TYPE "portableModel")

This line performs various setup necessary to configure and build a Portable Model item. (These settings must be performed before the project command on the next line.)

project(ex_model_Ar_P_Morse)

This line tells CMake to create a "project" with name equal to the item's name ex_model_Ar_P_Morse and that the item does not explicitly require compiler to be built.

kim_api_items_setup_after_project(ITEM_TYPE "portableModel")

This line performs various setup necessary to configure and build a Portable Model item. (These settings must be performed after the project command on the previous line.)

add_kim_api_model_library(
NAME ${PROJECT_NAME}
DRIVER_NAME "ex_model_driver_P_Morse"
PARAMETER_FILES "ex_model_Ar_P_Morse.params"
)

These lines register the item with the KIM API CMake build system and provide necessary metadata. The NAME argument is required and here the CMake variable PROJECT_NAME, which was set as a result of the project command (above), is used to provide the name of the Portable Model item.

The DRIVER_NAME argument specifies the Model Driver used used by Portable Model item. This argument is required.

The PARAMETER_FILES argument specifies an ordered, space separated list of parameter files required for use by the Model Driver. In this case there is just a single parameter file, but in general a Model Driver may require any number of such files. In addition to the number of parameter files, the Model Driver also specifies the order in which they must be listed and the file format(s) for their content.

There is also an additional (optional) argument METADATA_FILES. This can be set to a space separated list of file names that should be included with the Portable Model item as metadata files. These metadata files will not be directly used by the KIM API in any way, but they may be accessed through the KIM::Collections interface.

Portable Model (not using a Model Driver) CMakeLists.txt files

Here is the CMakeLists.txt file for the example Portable Model ex_model_Ar_P_Morse_07C.

cmake_minimum_required(VERSION 3.10)
list(APPEND CMAKE_PREFIX_PATH $ENV{KIM_API_CMAKE_PREFIX_DIR})
find_package(KIM-API-ITEMS 2.2 REQUIRED CONFIG)
kim_api_items_setup_before_project(ITEM_TYPE "portableModel")
project(ex_model_Ar_P_Morse_07C LANGUAGES C)
kim_api_items_setup_after_project(ITEM_TYPE "portableModel")
add_kim_api_model_library(
NAME ${PROJECT_NAME}
CREATE_ROUTINE_NAME "model_create"
CREATE_ROUTINE_LANGUAGE "c"
)
target_sources(${PROJECT_NAME} PRIVATE ${PROJECT_NAME}.c)

Let us go through this line by line to explain.

cmake_minimum_required(VERSION 3.10)

This line ensures that an appropriate version of CMake is being used.

list(APPEND CMAKE_PREFIX_PATH $ENV{KIM_API_CMAKE_PREFIX_DIR})
find_package(KIM-API-ITEMS 2.2 REQUIRED CONFIG)

These lines tell CMake to find the settings for building KIM API items with the KIM API library installed on the system.

kim_api_items_setup_before_project(ITEM_TYPE "portableModel")

This line performs various setup necessary to configure and build a Portable Model item. (These settings must be performed before the project command on the next line.)

project(ex_model_Ar_P_Morse_07C LANGUAGES C)

This line tells CMake to create a "project" with name equal to the item's name ex_model_Ar_P_Morse_07C and that the item will require a C compiler to be built.

kim_api_items_setup_after_project(ITEM_TYPE "portableModel")

This line performs various setup necessary to configure and build a Portable Model item. (These settings must be performed after the project command on the previous line.)

add_kim_api_model_library(
NAME ${PROJECT_NAME}
CREATE_ROUTINE_NAME "model_create"
CREATE_ROUTINE_LANGUAGE "c"
)

These lines register the item with the KIM API CMake build system and provide necessary metadata. The NAME argument is required and here the CMake variable PROJECT_NAME, which was set as a result of the project command (above), is used to provide the name of the Portable Model item.

The CREATE_ROUTINE_NAME argument specifies the identifier used to define the KIM::ModelCreate routine for the item. This argument is required.

The CREATE_ROUTINE_LANGUAGE argument specifies the programming language in which the create routine is written (valid values are: cpp, c, and fortran).

There is also an additional (optional) argument METADATA_FILES. This can be set to a space separated list of file names that should be included with the Portable Model item as metadata files. These metadata files will not be directly used by the KIM API in any way, but they may be accessed through the KIM::Collections interface.

target_sources(${PROJECT_NAME} PRIVATE ${PROJECT_NAME}.c)

This line associates the item's source code files with its CMake "target", which is set to the value given for the NAME argument in the call to add_kim_api_model_library. After the PRIVATE keyword a space separated list of source code file names can be given. This list of files should contain all source code (not header) files that are necessary to compile and build the Portable Model item. In this example there is just a single C soruce file with the same name as the item.

Simulator Model CMakeLists.txt files

Here is the CMakeLists.txt file for the example Simulator Model Sim_LAMMPS_LJcut_AkersonElliott_Alchemy_PbAu.

cmake_minimum_required(VERSION 3.10)
list(APPEND CMAKE_PREFIX_PATH $ENV{KIM_API_CMAKE_PREFIX_DIR})
find_package(KIM-API-ITEMS 2.2 REQUIRED CONFIG)
kim_api_items_setup_before_project(ITEM_TYPE "simulatorModel")
project(Sim_LAMMPS_LJcut_AkersonElliott_Alchemy_PbAu)
kim_api_items_setup_after_project(ITEM_TYPE "simulatorModel")
add_kim_api_model_library(
NAME "${PROJECT_NAME}"
SM_SPEC_FILE "smspec.edn"
PARAMETER_FILES "Alchemy_PbAu.in"
)

Let us go through this line by line to explain.

cmake_minimum_required(VERSION 3.10)

This line ensures that an appropriate version of CMake is being used.

list(APPEND CMAKE_PREFIX_PATH $ENV{KIM_API_CMAKE_PREFIX_DIR})
find_package(KIM-API-ITEMS 2.2 REQUIRED CONFIG)

These lines tell CMake to find the settings for building KIM API items with the KIM API library installed on the system.

kim_api_items_setup_before_project(ITEM_TYPE "simulatorModel")

This line performs various setup necessary to configure and build a Simulator Model item. (These settings must be performed before the project command on the next line.)

project(Sim_LAMMPS_LJcut_AkersonElliott_Alchemy_PbAu)

This line tells CMake to create a "project" with name equal to the item's name Sim_LAMMPS_LJcut_AkersonElliott_Alchemy_PbAu and that the item will not explicitly require a compiler to be built.

kim_api_items_setup_after_project(ITEM_TYPE "simulatorModel")

This line performs various setup necessary to configure and build a Simulator Model item. (These settings must be performed after the project command on the previous line.)

add_kim_api_model_library(
NAME "${PROJECT_NAME}"
SM_SPEC_FILE "smspec.edn"
PARAMETER_FILES "Alchemy_PbAu.in"
)

These lines register the item with the KIM API CMake build system and provide necessary metadata. The NAME argument is required and here the CMake variable PROJECT_NAME, which was set as a result of the project command (above), is used to provide the name of the Simulator Model item.

The SM_SPEC_FILE argument specifies the name of the KIM API/SMI Specification File for the Simulator Model.

The PARAMETER_FILES argument specifies an ordered, space separated list of parameter files required for use by the Simulator Model. In this case there is just a single parameter file, but in general a Simulator Model may require any number of such files. In addition to the number of parameter files, the Simulator Model also specifies the order in which they must be listed and the file format(s) for their content.

There is also an additional (optional) argument METADATA_FILES. This can be set to a space separated list of file names that should be included with the Simulator Model item as metadata files. These metadata files will not be directly used by the KIM API in any way, but they may be accessed through the KIM::Collections interface.

Simulators using CMake CMakeLists.txt files

Todo:
Add description of CMakeLists.txt files for simulators/projects that use the KIM-API library and use CMake.

For now, see utility_forces_numer_deriv and its CMakeLists.txt file given here.

cmake_minimum_required(VERSION 3.10)
project(utility_forces_numer_deriv VERSION 1.0.0 LANGUAGES Fortran)
# Enable C++ to workaround https://gitlab.kitware.com/cmake/cmake/-/issues/20438
enable_language(CXX)
find_package(KIM-API 2.2 REQUIRED CONFIG)
add_executable(${PROJECT_NAME} ${PROJECT_NAME}.f90)
target_link_libraries(${PROJECT_NAME} KIM-API::kim-api)

Simulators not using CMake

Todo:
Add description of getting build details via pkg-config for simulators/projects that use the KIM-API library but do not use CMake.

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