From 2307c2652c1dc61211efee59d98c50879e32fd55 Mon Sep 17 00:00:00 2001 From: ilia Nikiforov Date: Fri, 6 Feb 2026 15:44:16 -0600 Subject: [PATCH 01/12] Update KIM unit tests and unit test documentation; Unit tests have broken due to using models that have been upversioned. Update models, make tests confirm that double values are near rather than exact string matches. Update documentation to reflect what models are required to run extra unit tests. --- doc/src/Build_extras.rst | 4 +-- unittest/commands/test_kim_commands.cpp | 35 ++++++++++++++----------- 2 files changed, 22 insertions(+), 17 deletions(-) diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index 4efd7e1e13b..cd3738c1778 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -491,8 +491,8 @@ Enabling the extra unit tests have some requirements, `kim-property installation `_. * It is also necessary to install the following KIM models: - * ``EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000`` - * ``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005`` + * ``EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_001`` + * ``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_006`` * ``LennardJones612_UniversalShifted__MO_959249795837_003`` See `Obtaining KIM Models `_ diff --git a/unittest/commands/test_kim_commands.cpp b/unittest/commands/test_kim_commands.cpp index 17dc8dba060..7d7f310674d 100644 --- a/unittest/commands/test_kim_commands.cpp +++ b/unittest/commands/test_kim_commands.cpp @@ -34,6 +34,8 @@ using LAMMPS_NS::utils::split_words; namespace LAMMPS_NS { using ::testing::StrEq; +using ::testing::DoubleNear; +using ::testing::Eq; class KimCommandsTest : public LAMMPSTest { protected: @@ -577,14 +579,14 @@ TEST_F(KimCommandsTest, kim_query) command("clear"); command("kim query latconst_1 get_lattice_constant_cubic " "crystal=[fcc] species=[Al] units=[angstrom] " - "model=[EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005]"); + "model=[EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_006]"); END_HIDE_OUTPUT(); - ASSERT_THAT(variable->retrieve("latconst_1"), StrEq("4.032082033157349")); + ASSERT_THAT(std::stod(variable->retrieve("latconst_1")), DoubleNear(4.032082033157349, 1.e-2)); BEGIN_HIDE_OUTPUT(); command("clear"); - command("kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal"); + command("kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_006 metal"); command("kim query latconst_1 get_lattice_constant_cubic crystal=[fcc] species=[Al] " "units=[angstrom]"); @@ -593,50 +595,53 @@ TEST_F(KimCommandsTest, kim_query) "model=[LennardJones612_UniversalShifted__MO_959249795837_003]"); END_HIDE_OUTPUT(); - ASSERT_THAT(variable->retrieve("latconst_1"), StrEq("4.032082033157349")); - ASSERT_THAT(variable->retrieve("latconst_2"), StrEq("3.328125931322575")); + ASSERT_THAT(std::stod(variable->retrieve("latconst_1")), DoubleNear(4.032082033157349, 1.e-2)); + ASSERT_THAT(std::stod(variable->retrieve("latconst_2")), DoubleNear(3.328125931322575, 1.e-2)); BEGIN_HIDE_OUTPUT(); command("clear"); - command("kim init EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000 metal"); + command("kim init EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_001 metal"); command("kim query latconst split get_lattice_constant_hexagonal crystal=[hcp] species=[Zr] " "units=[angstrom]"); END_HIDE_OUTPUT(); - ASSERT_THAT(variable->retrieve("latconst_1"), StrEq("3.234055244384789")); - ASSERT_THAT(variable->retrieve("latconst_2"), StrEq("5.167650199630013")); + ASSERT_THAT(std::stod(variable->retrieve("latconst_1")), DoubleNear(3.208725140430033, 1.e-2)); + ASSERT_THAT(std::stod(variable->retrieve("latconst_2")), DoubleNear(5.239826212595919, 1.e-2)); BEGIN_HIDE_OUTPUT(); command("clear"); command("kim query latconst index get_lattice_constant_hexagonal " "crystal=[hcp] species=[Zr] units=[angstrom] " - "model=[EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000]"); + "model=[EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_001]"); END_HIDE_OUTPUT(); - ASSERT_THAT(variable->retrieve("latconst"), StrEq("3.234055244384789")); + ASSERT_THAT(std::stod(variable->retrieve("latconst")), DoubleNear(3.208725140430033, 1.e-2)); BEGIN_HIDE_OUTPUT(); command("variable latconst delete"); command("clear"); - command("kim init EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000 metal"); + command("kim init EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_001 metal"); command("kim query latconst list get_lattice_constant_hexagonal crystal=[hcp] species=[Zr] " "units=[angstrom]"); END_HIDE_OUTPUT(); - ASSERT_THAT(variable->retrieve("latconst"), StrEq("3.234055244384789 5.167650199630013")); + std::vector latconsts = utils::split_words(variable->retrieve("latconst")); + ASSERT_THAT(latconsts.size(), Eq(2)); + ASSERT_THAT(std::stod(latconsts[0]), DoubleNear(3.208725140430033, 1.e-2)); + ASSERT_THAT(std::stod(latconsts[1]), DoubleNear(5.239826212595919, 1.e-2)); BEGIN_HIDE_OUTPUT(); command("clear"); - command("kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal"); + command("kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_006 metal"); command("kim query alpha get_linear_thermal_expansion_coefficient_cubic " "crystal=[fcc] species=[Al] units=[1/K] temperature=[293.15] " "temperature_units=[K]"); END_HIDE_OUTPUT(); - ASSERT_THAT(variable->retrieve("alpha"), StrEq("1.656579473023212e-05")); + ASSERT_THAT(std::stod(variable->retrieve("alpha")), DoubleNear(1.658279376744496e-05, 1e-7)); BEGIN_HIDE_OUTPUT(); command("clear"); @@ -645,7 +650,7 @@ TEST_F(KimCommandsTest, kim_query) END_HIDE_OUTPUT(); std::string model_list = variable->retrieve("model_list"); - auto n = model_list.find("EAM_Dynamo_LiuErcolessiAdams_2004_Al__MO_051157671505_000"); + auto n = model_list.find("EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_006"); ASSERT_TRUE(n != std::string::npos); BEGIN_HIDE_OUTPUT(); From 53ca1b215a01b706bd0772c68e6bc95e8ed4b375 Mon Sep 17 00:00:00 2001 From: ilia Nikiforov Date: Fri, 6 Feb 2026 15:52:37 -0600 Subject: [PATCH 02/12] document get_available_models kim query behavior --- doc/src/kim_commands.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/src/kim_commands.rst b/doc/src/kim_commands.rst index edc4f3548eb..d090520baae 100644 --- a/doc/src/kim_commands.rst +++ b/doc/src/kim_commands.rst @@ -416,7 +416,8 @@ Using OpenKIM Web Queries in LAMMPS (*kim query*) The *kim query* command performs a web query to retrieve the predictions of an IM set by *kim init* for material properties archived in -`OpenKIM `_. +`OpenKIM `_, or to obtain a list of available models +that support a given set of atomic species. Syntax ------ @@ -483,6 +484,12 @@ and format of their values depend on the query function used. The current list of query functions is available on the OpenKIM webpage at `https://openkim.org/doc/usage/kim-query `_. +.. note:: + + The *get_available_models* function's output is postprocessed to LAMMPS to only + save the names of the installed models to the variable. Models that were found + by the query but not installed are written to the LAMMPS log file. + .. note:: All query functions, except *get_available_models*, require the From 0a6fc98de3a782f30dfd2512b0bb50547e75e7a7 Mon Sep 17 00:00:00 2001 From: ilia Nikiforov Date: Fri, 6 Feb 2026 16:10:22 -0600 Subject: [PATCH 03/12] Explain that the universal Lennard-Jones is bundled with the API --- doc/src/Build_extras.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index cd3738c1778..b9b74247705 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -493,7 +493,7 @@ Enabling the extra unit tests have some requirements, * ``EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_001`` * ``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_006`` - * ``LennardJones612_UniversalShifted__MO_959249795837_003`` + * ``LennardJones612_UniversalShifted__MO_959249795837_003`` (this model is an example model automatically built with the API unless explicitly disabled) See `Obtaining KIM Models `_ to learn how to install a pre-built binary of the OpenKIM Repository of From 793d3b05ec6cb94e974dcf687fbff692b3313d77 Mon Sep 17 00:00:00 2001 From: ilia Nikiforov Date: Fri, 6 Mar 2026 17:48:29 -0600 Subject: [PATCH 04/12] Update KIM CMakeLists to 2.4.2 --- cmake/Modules/Packages/KIM.cmake | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cmake/Modules/Packages/KIM.cmake b/cmake/Modules/Packages/KIM.cmake index d724ec18fc7..8dee1f7f2e4 100644 --- a/cmake/Modules/Packages/KIM.cmake +++ b/cmake/Modules/Packages/KIM.cmake @@ -30,8 +30,8 @@ if(DOWNLOAD_KIM) include(ExternalProject) enable_language(C) enable_language(Fortran) - set(KIM_URL "https://s3.openkim.org/kim-api/kim-api-2.2.1.txz" CACHE STRING "URL for KIM tarball") - set(KIM_MD5 "ae1ddda2ef7017ea07934e519d023dca" CACHE STRING "MD5 checksum of KIM tarball") + set(KIM_URL "https://s3.openkim.org/kim-api/kim-api-2.4.2.txz" CACHE STRING "URL for KIM tarball") + set(KIM_MD5 "bd51faa7edfaab437047aea0c25a5dfb" CACHE STRING "MD5 checksum of KIM tarball") mark_as_advanced(KIM_URL) mark_as_advanced(KIM_MD5) ExternalProject_Add(kim_build From 008eda694e72e72a9e68951d74436c6dd04f8266 Mon Sep 17 00:00:00 2001 From: ilia Nikiforov Date: Sat, 7 Mar 2026 11:06:55 -0600 Subject: [PATCH 05/12] Update KIM build documentation The OpenKIM model library is no longer updated, it is recommended that users install models individually. Also clarify that usage of DOWNLOAD_KIM is not recommended --- doc/src/Build_extras.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index b9b74247705..258f371e845 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -382,9 +382,16 @@ option in preparations to run on Aurora system at Argonne. KIM package --------------------- -To build with this package, the KIM library with API v2 must be downloaded -and built on your system. It must include the KIM models that you want to -use with LAMMPS. +To build with this package, the KIM API v2.0+ must be downloaded +and built on your system. See +`Obtaining KIM Models `_ to +learn how to install the KIM API, as well as how to install any models you +wish to use afterward. +See the list of all KIM models here: https://openkim.org/browse/models + +(Also note that when downloading and installing from source +the KIM API library with all its models, may take a long time (tens of +minutes to hours) to build. Of course you only need to do that once.) If you would like to use the :doc:`kim query ` command, you also need to have libcurl installed with the matching @@ -400,16 +407,6 @@ channel as ``conda install kim-property`` if LAMMPS is built in Conda. More detailed information is available at: `kim-property installation `_. -In addition to installing the KIM API, it is also necessary to install the -library of KIM models (interatomic potentials). -See `Obtaining KIM Models `_ to -learn how to install a pre-build binary of the OpenKIM Repository of Models. -See the list of all KIM models here: https://openkim.org/browse/models - -(Also note that when downloading and installing from source -the KIM API library with all its models, may take a long time (tens of -minutes to hours) to build. Of course you only need to do that once.) - .. tabs:: .. tab:: CMake build @@ -426,11 +423,14 @@ minutes to hours) to build. Of course you only need to do that once.) # value = no (default) or yes If ``DOWNLOAD_KIM`` is set to ``yes`` (or ``on``), the KIM API library - will be downloaded and built inside the CMake build directory. If + will be downloaded and built inside the CMake build directory. Note that + in most cases it is recommended that you do not use this option, and instead + provide a KIM API installation yourself before building LAMMPS. If the KIM library is already installed on your system (in a location where CMake cannot find it), you may need to set the ``PKG_CONFIG_PATH`` environment variable so that libkim-api can be - found, or run the command ``source kim-api-activate``. + found, or run the command ``source kim-api-activate``. If CMake can't find + the KIM API, the ``DOWNLOAD_KIM`` option will be enabled automatically. Extra unit tests can only be available if they are explicitly requested (``KIM_EXTRA_UNITTESTS`` is set to ``yes`` (or ``on``)) and the prerequisites From 0c8fe15c6a2c80dd2365919bff7d2c57c773d8b1 Mon Sep 17 00:00:00 2001 From: ilia Nikiforov Date: Sun, 8 Mar 2026 13:32:39 -0500 Subject: [PATCH 06/12] add warning when KIM-API not found --- cmake/Modules/Packages/KIM.cmake | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/cmake/Modules/Packages/KIM.cmake b/cmake/Modules/Packages/KIM.cmake index 8dee1f7f2e4..438779deefa 100644 --- a/cmake/Modules/Packages/KIM.cmake +++ b/cmake/Modules/Packages/KIM.cmake @@ -24,6 +24,12 @@ if(PKG_CONFIG_FOUND) set(DOWNLOAD_KIM_DEFAULT OFF) endif() endif() +if(NOT KIM-API_FOUND) + message(WARNING "KIM-API was not found, so we will download and build our own. " + "If you intend to use LAMMPS with a pre-installed KIM-API, " + "you may need to set PKG_CONFIG_PATH, or run the command " + "'source kim-api-activate', then re-run CMake.") +endif() option(DOWNLOAD_KIM "Download KIM-API from OpenKIM instead of using an already installed one" ${DOWNLOAD_KIM_DEFAULT}) if(DOWNLOAD_KIM) message(STATUS "KIM-API download requested - we will build our own") From 9fc5af08335e723b501614ef8270afafb1851b4b Mon Sep 17 00:00:00 2001 From: ilia Nikiforov Date: Sun, 8 Mar 2026 13:39:15 -0500 Subject: [PATCH 07/12] Remove comment about openkim-models taking a long time --- doc/src/Build_extras.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index 5ac225408b6..f401d719ec6 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -393,10 +393,6 @@ learn how to install the KIM API, as well as how to install any models you wish to use afterward. See the list of all KIM models here: https://openkim.org/browse/models -(Also note that when downloading and installing from source -the KIM API library with all its models, may take a long time (tens of -minutes to hours) to build. Of course you only need to do that once.) - If you would like to use the :doc:`kim query ` command, you also need to have libcurl installed with the matching development headers and the curl-config tool. From 1df08e307fb1006b4c3642729377b5b01274b10f Mon Sep 17 00:00:00 2001 From: ilia Nikiforov Date: Sun, 8 Mar 2026 14:09:45 -0500 Subject: [PATCH 08/12] fix trailing whitespace --- doc/src/Build_extras.rst | 2 +- doc/src/kim_commands.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index f401d719ec6..0a32819871f 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -387,7 +387,7 @@ KIM package --------------------- To build with this package, the KIM API v2.0+ must be downloaded -and built on your system. See +and built on your system. See `Obtaining KIM Models `_ to learn how to install the KIM API, as well as how to install any models you wish to use afterward. diff --git a/doc/src/kim_commands.rst b/doc/src/kim_commands.rst index d090520baae..d2e8337d451 100644 --- a/doc/src/kim_commands.rst +++ b/doc/src/kim_commands.rst @@ -416,7 +416,7 @@ Using OpenKIM Web Queries in LAMMPS (*kim query*) The *kim query* command performs a web query to retrieve the predictions of an IM set by *kim init* for material properties archived in -`OpenKIM `_, or to obtain a list of available models +`OpenKIM `_, or to obtain a list of available models that support a given set of atomic species. Syntax From bb415edfd719e36ad8e16e40ed9b4016691fe772 Mon Sep 17 00:00:00 2001 From: ilia Nikiforov <78983960+ilia-nikiforov-umn@users.noreply.github.com> Date: Sun, 8 Mar 2026 16:44:20 -0500 Subject: [PATCH 09/12] Update doc/src/kim_commands.rst Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- doc/src/kim_commands.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/src/kim_commands.rst b/doc/src/kim_commands.rst index d2e8337d451..bf21112bdc6 100644 --- a/doc/src/kim_commands.rst +++ b/doc/src/kim_commands.rst @@ -486,9 +486,9 @@ of query functions is available on the OpenKIM webpage at .. note:: - The *get_available_models* function's output is postprocessed to LAMMPS to only - save the names of the installed models to the variable. Models that were found - by the query but not installed are written to the LAMMPS log file. + The *get_available_models* function's output is post-processed by LAMMPS so that + only the names of models that are currently installed are stored in the variable. + Matching models that are not installed are instead written to the LAMMPS log file. .. note:: From 86c8fc0a35d1b2c698cb11ac2e4986d0028f929f Mon Sep 17 00:00:00 2001 From: ilia Nikiforov <78983960+ilia-nikiforov-umn@users.noreply.github.com> Date: Sun, 8 Mar 2026 16:49:53 -0500 Subject: [PATCH 10/12] Update doc/src/Build_extras.rst Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- doc/src/Build_extras.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index 0a32819871f..ff99b1d8db9 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -429,8 +429,9 @@ detailed information is available at: the KIM library is already installed on your system (in a location where CMake cannot find it), you may need to set the ``PKG_CONFIG_PATH`` environment variable so that libkim-api can be - found, or run the command ``source kim-api-activate``. If CMake can't find - the KIM API, the ``DOWNLOAD_KIM`` option will be enabled automatically. + found, or run the command ``source kim-api-activate``. If CMake cannot find + the KIM API when configuring for the first time (or after clearing the + CMake cache), the default value of the ``DOWNLOAD_KIM`` option will be ``yes``. Extra unit tests can only be available if they are explicitly requested (``KIM_EXTRA_UNITTESTS`` is set to ``yes`` (or ``on``)) and the prerequisites From 39bccb1c341a823d58f821624c1cf0c6cc324b98 Mon Sep 17 00:00:00 2001 From: ilia Nikiforov Date: Sun, 8 Mar 2026 17:06:14 -0500 Subject: [PATCH 11/12] print warnings only if DOWNLOAD_KIM is on, and print a different warning whether KIM API is found or not --- cmake/Modules/Packages/KIM.cmake | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/cmake/Modules/Packages/KIM.cmake b/cmake/Modules/Packages/KIM.cmake index 438779deefa..196b83e0b35 100644 --- a/cmake/Modules/Packages/KIM.cmake +++ b/cmake/Modules/Packages/KIM.cmake @@ -24,15 +24,21 @@ if(PKG_CONFIG_FOUND) set(DOWNLOAD_KIM_DEFAULT OFF) endif() endif() -if(NOT KIM-API_FOUND) - message(WARNING "KIM-API was not found, so we will download and build our own. " - "If you intend to use LAMMPS with a pre-installed KIM-API, " - "you may need to set PKG_CONFIG_PATH, or run the command " - "'source kim-api-activate', then re-run CMake.") -endif() option(DOWNLOAD_KIM "Download KIM-API from OpenKIM instead of using an already installed one" ${DOWNLOAD_KIM_DEFAULT}) if(DOWNLOAD_KIM) - message(STATUS "KIM-API download requested - we will build our own") + message(STATUS "KIM-API download requested - we will build our own") + if(NOT KIM-API_FOUND) + message(WARNING "KIM-API was not found, and DOWNLOAD_KIM is on, " + "so we will download and build our own. " + "If you intend to use LAMMPS with a pre-installed KIM-API, " + "you may need to set PKG_CONFIG_PATH, or run the command " + "'source kim-api-activate', then re-run CMake.") + else() + message(WARNING "KIM-API was was found, but DOWNLOAD_KIM is on, " + "so we will download and build our own. If you intend " + "to use LAMMPS with your pre-installed KIM-API, you " + "should disable DOWNLOAD_KIM and re-run CMake.") + endif() include(ExternalProject) enable_language(C) enable_language(Fortran) From 674e0331581c6502602183d224f64012cf0c417e Mon Sep 17 00:00:00 2001 From: ilia Nikiforov Date: Sun, 8 Mar 2026 17:07:55 -0500 Subject: [PATCH 12/12] fix whitespace --- cmake/Modules/Packages/KIM.cmake | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmake/Modules/Packages/KIM.cmake b/cmake/Modules/Packages/KIM.cmake index 196b83e0b35..c290285c303 100644 --- a/cmake/Modules/Packages/KIM.cmake +++ b/cmake/Modules/Packages/KIM.cmake @@ -26,7 +26,7 @@ if(PKG_CONFIG_FOUND) endif() option(DOWNLOAD_KIM "Download KIM-API from OpenKIM instead of using an already installed one" ${DOWNLOAD_KIM_DEFAULT}) if(DOWNLOAD_KIM) - message(STATUS "KIM-API download requested - we will build our own") + message(STATUS "KIM-API download requested - we will build our own") if(NOT KIM-API_FOUND) message(WARNING "KIM-API was not found, and DOWNLOAD_KIM is on, " "so we will download and build our own. "