kim-api  2.3.1-git+v2.3.0-git-2-g378406f9.GNU.GNU. An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
INSTALL
Go to the documentation of this file.
1 #
2 # KIM-API: An API for interatomic models
3 # Copyright (c) 2013--2022, Regents of the University of Minnesota.
5 #
6 # Contributors:
7 # Ryan S. Elliott
9 #
11 #
12 # This library is free software; you can redistribute it and/or
13 # modify it under the terms of the GNU Lesser General Public
15 # version 2.1 of the License, or (at your option) any later version.
16 #
17 # This library is distributed in the hope that it will be useful,
18 # but WITHOUT ANY WARRANTY; without even the implied warranty of
19 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 # Lesser General Public License for more details.
21 #
22 # You should have received a copy of the GNU Lesser General Public License
23 # along with this library; if not, write to the Free Software Foundation,
24 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
25 #
26
27 #
28 # Release: This file is part of the kim-api.git repository.
29 #
30
31
32 ============================= The KIM API package =============================
33
34 This file contains instructions for installing the KIM API package.
35
36
38
39 A. System requirements
40
41 B. Quick start
42
43 C. Package concepts and operation overview
44  C.1 KIM API library
45  C.2 Collections for Model Drivers (MDs), Portable Models (PMs), and
46  Simulator Models (SMs)
47  C.2.1 The system-collection
48  C.2.2 The user-collection
49  C.2.3 The environment-variable-collection
50  C.2.4 The CWD-collection
51  C.3 Helper utilities
52
53 D. KIM API Installation
54  D.1 Typical build scenario
55  D.2 CMake build options
56  D.2.1 Compiler selection
57  D.2.2 CMAKE_BUILD_TYPE
58  D.2.3 Installation prefix
59  D.2.4 KIM API specific build options
60  D.3 Installing multiple versions
61  D.4 Uninstall the KIM API
62
63 E. Adding MDs, PMs, and SMs to the collections
64  E.1 Adding MDs, PMs, and SMs to the system-collection
65  E.2 Adding MDs, PMs, and SMs to the user-collection
66  E.3 Adding MDs, PMs, and SMs to the environment-variable-collection
67  E.4 Adding MDs, PMs, and SMs to the CWD-collection
68  E.5 Adding MDs, PMs, and SMs from a local source directory
69  E.6 Manually adding MDs, PMs, and SMs
70
71
72 -------------------------------------------------------------------------------
73
74 A. SYSTEM REQUIREMENTS
75
76
77 To install and run the KIM API package you need the following:
78
79 1. A Unix/Linux/macOS system.
80
81 2. CMake (3.10 or later).
82
83 3. GNU compilers (gcc, g++, gfortran) version 4.8.x or higher or the
84  corresponding Intel compilers, version 11.1 or higher. Other compilers may
85  also work.
86
87 4. (optional) The 'xxd' utility (distributed as part of the vim package).
88  If available, provides faster builds than without.
89
90 5. wget or curl, sed, grep, tar, uname, etc. (used by the
91  kim-api-collections-management utility).
92
93 6. Doxygen and Graphviz (for generating the documentation).
94
95 7. The bash-completion package (for facilitating command-line usage of the
96  helper utilities).
97
98 8. pkg-config can be used by code needing to link against the kim-api library.
99
100
101 -------------------------------------------------------------------------------
102
103 B. QUICK START: For those who don't like to read and are a bit audacious.
104
105 Try the following:
106
107  $mkdir build && cd build 108$ cmake .. -DCMAKE_BUILD_TYPE=Release
109  $make 110$ sudo make install
111  $sudo ldconfig 112 113 For more information, see section D. 114 115 ------------------------------------------------------------------------------- 116 117 C. PACKAGE LAYOUT AND OPERATION OVERVIEW 118 119 120 The KIM API package is a system-level library that aims to give computer 121 programmers the ability to write atomistic or molecular simulation programs 122 (Simulators) that can seamlessly interface with implementations of interatomic 123 potentials (Portable Models, PMs), regardless of the programming language in 124 which the codes are written. The KIM API package provides a dedicated Portable 125 Model Interface (PMI) for use by simulators and PMs and referred to as the KIM 126 API/PMI. A PM can include code and parameters all in one. Or, a PM can 127 include just parameters and use a separate Model Driver (MD) library containing 128 the code. There are also Simulator Models (SMs) that only work with a specific 129 simulator. The KIM API package provides a dedicated Simulator Model Interface 130 (SMI) for use by simulators and SMs and referred to as the KIM API/SMI. In 131 addition to the main KIM API library, a small number of associated helper 132 utilities are provided. 133 134 C.1. KIM API Library 135 136 The KIM API library provides the necessary routines for a Simulator to interact 137 with a PM or SM. It also contains an interface for discovering what MDs, PMs, 138 and SMs are available in the KIM API Collections. MDs, PMs, and SMs are built 139 and linked against the KIM API library, then installed in one of the 140 collections (see below) so that they are available for use with a simulator. 141 Simulators are built and linked against the KIM API library so that they can 142 access and use any of the available PMs and/or SM in the various collections. 143 144 C.2 COLLECTIONS FOR MODEL DRIVERS (MDs), PORTABLE MODELS (PMs), AND 145 SIMULATOR MODELS (SMs) 146 147 The KIM API supports four Collections of Items. These are the 148 "system-collection", the "user-collection", the 149 "environment-variable-collection", and the "CWD-collection" as described below. 150 Each collection consists of separate sets of three Item Types: MDs, PMs, and 151 SMs. When the KIM API needs to use a particular MD, PD, or SM, it looks for 152 the item by type and name, first in the CWD-collection, then in the 153 environment-variable-collection, then in the user-collection, and finally in 154 the system-collection. It uses the first match that it finds. Note, it is 155 possible for a PM and its associated MD to be located in different collections. 156 The search for each is a separate and independent procedure. 157 158 See also the documentation for the Collections Interface (c++: 159 KIM::Collections; c: KIM_Collections; and Fortran: kim_collections_module). 160 161 C.2.1 THE SYSTEM-COLLECTION 162 163 The system-collection is a collection of MDs, PMs, and SMs that are available 164 to all simulators that use the KIM API library. By default, this collection is 165 located in the same subdirectory as the KIM API library. (See also the 166 "KIM_API_SYSTEM_*_DIR" build options in section D.2.4, below.) 167 168 MDs, PMs, and SMs may be built and installed to the system-collection at 169 anytime after the KIM API has been built and installed. 170 171 C.2.2 THE USER-COLLECTION 172 173 The user-collection is a collection of MDs, PMs, and SMs that are available 174 only to the user who owns the process for the simulator that uses the KIM API 175 library. This collection is located in subdirectories that are specified by a 176 configuration file. The user-collection may be populated with MDs, PMs, and 177 SMs after the KIM API has been built and installed. 178 179 The configuration file is named "${HOME}/.kim-api/<kim-api-uid>/config" by
180 default, where <kim-api-uid> is a unique identifier for the particular
181 installation of the kim-api being used (this allows multiple, independent,
182 installations on a single machine). Here "${HOME}" is the user's home 183 directory. (See item D below for build options controlling this default file 184 name.) If the "KIM_API_CONFIGURATION_FILE" environment variable is set, its 185 value (interpreted as an absolute file name) will supersede the default 186 location and name of the configuration file. For example, the following 187 commands will instruct the KIM API library to use a file named "kim-config" in 188 the /my-kim-stuff folder 189 190$ export KIM_API_CONFIGURATION_FILE=/my-kim-stuff/kim-config
191
192 If the configuration file does not exist, the KIM API library will create it
193 with a default configuration specifying that the user-collection files are
194 stored in "${HOME}/.kim-api/<kim-api-uid>/model-drivers/", 195 "${HOME}/.kim-api/<kim-api-uid>/portable-models/", and
196 "${HOME}/.kim-api/<kim-api-uid>/simulator-models/". More generally, the values 197 in the configuration file may contain colon ':' (on Windows: semi-colon ';') 198 separated lists of fully-qualified directory names (starting, strictly, with 199 '/', '~/' or a root drive letter like 'C:/'). (See item D below for build 200 options controlling these defaults.) 201 202 C.2.3 THE ENVIRONMENT-VARIABLE-COLLECTION 203 204 The environment-variable-collection is a collection of MDs, PMs, and SMs that 205 are specified by the run-time environment of the process for the simulator that 206 uses the KIM API library. The locations of this collection are specified by 207 the environment variables "KIM_API_MODEL_DRIVERS_DIR", 208 "KIM_API_PORTABLE_MODELS_DIR", and "KIM_API_SIMULATOR_MODELS_DIR". These 209 variables should contain colon ':' (on Windows: semi-colon ';') separated lists 210 of absolute directory names where the collection MDs, PMs, and SMs, respectively, 211 are located. (For example, in bash you could execute the command 212 213$ export KIM_API_PORTABLE_MODELS_DIR=/my-kim-stuff/models-i-am-developing:/my-kim-stuff/misc-portable-models
214
215 to have the KIM API look for PMs in /my-kim-stuff/models-i-am-developing first
216 and then look in /my-kim-stuff/misc-portable-models. (Similarly for MDs and
217 SMs.) The environment-variable-collection may be populated with MDs, PMs, and
218 SMs after the KIM API has been built and installed.
219
220 C.2.4 THE CWD-COLLECTION
221
222 The CWD-collection is a collection of MDs, PMs, SMs that are available to a
223 simulator at run-time. The collection is located in the simulator process's
224 current working directory (CWD). The CWD-collection may be populated with MDs,
225 PMs, and SMs after the KIM API has been built and installed.
226
227 C.3 HELPER UTILITIES
228
229 The KIM API package also includes a utility for managing the MDs, PMs, and SMs
230 contained in the various collections and for managing the configuration file.
231 This utility is called "kim-api-collections-management". The KIM API package
232 installs bash completion scripts that are designed to work with the
233 "bash-completion" package (https://github.com/scop/bash-completion). When
234 "bash-completion" is installed and activated on the system, tab-completions for
235 the collections management utility should be automatically loaded and available
236 for use.
237
238 In addition, when the KIM API package is installed to a "Local (non-global)"
239 (see D below) directory, the package also installs the "kim-api-activate" and
240 "kim-api-deactivate" scripts. The activate script adds the utilities to the
241 executable PATH, adds the KIM API library to the PKG_CONFIG_PATH so that the
242 pkg-config utility can find it, and loads bash tab-completion support for the
243 collections management utility. The deactivate script removes what the
245
246
247 -------------------------------------------------------------------------------
248
249 D. KIM API INSTALLATION
250
251 D.1 Typical Build Scenario
252
253 Here, the typical KIM API build and install process is detailed and the
254 system-collection is populated with the example MDs, PMs, and SMs, as well as a
255 single PM and its associated MD, both from openkim.org. Additionally, one of
256 the example simulators is copied to the user's home directory and used to test
257 the KIM API. The KIM API package uses the CMake build system. See the CMake
258 documentation (https://cmake.org/cmake/help/v3.10/) for help with CMake
259 settings. For some common CMake settings and KIM API specific settings, see
260 D.2 below.
261
262 The commands given below are for the bash shell.
263
264 By default packages are installed to the Global prefix directory "/usr/local".
265 Here we assume that "/usr/local/bin" is included as part of the system's
266 standard PATH setting.
267
268 First, we will create a working space and obtain the source package
269
270  $export WORKSPACE="${HOME}/kim-api-workspace"
271  $mkdir "${WORKSPACE}"
272  $cd "${WORKSPACE}
273  $wget https://s3.openkim.org/kim-api/kim-api-X.Y.Z.txz # replace X, Y, and Z with the current version numbers 274$ tar Jxvf kim-api-X.Y.Z.txz
275  $cd kim-api-X.Y.Z 276 277 We will set an environment variable to point the the KIM API source. 278 279$ export KIM_API_SOURCE="${WORKSPACE}/kim-api-X.Y.Z" # replace X, Y, and Z with the current version numbers 280 281 Next the configuration and build process begins. (Note: lines beginning with 282 "$", without leading whitespace, in this file are extracted and used in the KIM
283 API automated Continuous-Integration (CI) testing framework.)
284
285 $cd "${WORKSPACE}"
286 $mkdir build 287$ cd build
288 $cmake${KIM_API_SOURCE} -DCMAKE_BUILD_TYPE=Release
289 $make -j2 290 291 If you want, build the documentation. 292 293$ make docs
294
295 If you want, before installing the package, you can run the tests.
296
297 $make test 298 299 Now, install the package (and docs, if built). 300 301$ sudo make install
302 $sudo ldconfig # All linux systems should do this; on Redhat-like systems you may need to first add /usr/local/lib to /etc/ld.so.conf 303$ cp -r "${KIM_API_SOURCE}/examples/simulators/utility_forces_numer_deriv" "${WORKSPACE}/"
304 $cd "${WORKSPACE}"
305
306 If you want, you can now delete the source and build tree. However, you may
307 also want to preserve the "install_manifest.txt" file which would be needed for
308 uninstalling the KIM API package (see D.4 below).
309
310  $cp "${WORKSPACE}/build/install_manifest.txt" "${WORKSPACE}/install_manifest.txt" 311$ rm -r "${WORKSPACE}/build 312 313 Now, we can build the simulator using the KIM API library that we have just 314 installed. 315 316$ cd utility_forces_numer_deriv
317 $mkdir build 318$ cd build
319 $cmake .. 320$ make
321
322 Try it with one of the example models:
323
324 $printf "ex_model_Ar_P_LJ" | ./utility_forces_numer_deriv 325 326 Next, we can try it with a model installed from https://openkim.org: 327 328$ kim-api-collections-management install system --sudo EDIP_JustoBazantKaxiras_1998_Si__MO_958932894036_002
329 $printf "EDIP_JustoBazantKaxiras_1998_Si__MO_958932894036_002" | ./utility_forces_numer_deriv 330 331 Congratulations, you have now successfully installed the KIM API. If you would 332 like to learn more about the KIM API, read the documentation in the docs 333 directory (/usr/local/share/doc/kim-api). 334 335 If you would like to install the latest release of all models from 336 https://openkim.org, you can do: 337 338$ kim-api-collections-management install system --sudo OpenKIM
339
340 D.2 CMAKE BUILD OPTIONS
341
342 The KIM API defines a number of specific build options which are detailed in
343 this section. But first, some notes about a few important standard CMake
344 options.
345
346 D.2.1 COMPILER SELECTION
347
348 By default CMake will search for appropriate compilers available on your
349 system. Generally, it selects reasonable choices. However, if you wish to
350 force CMake to use specific compilers, you can do so with environment variables
351 set on the command line. For example, suppose you have the latest GNU Compiler
352 Collection (GCC) version X installed with the compilers named 'gcc-X', 'g++-X',
353 and 'gfortran-X', for the C, C++, and Fortran compilers, respectively. Then,
354 to force CMake to use these compilers, replace the command (from above)
355
356  $cmake .. -DCMAKE_BUILD_TYPE=Release 357 358 with 359 360$ CC=gcc-X CXX=g++-X FC=gfortran-X cmake .. -DCMAKE_BUILD_TYPE=Release
361
362 D.2.2 CMAKE_BUILD_TYPE
363
364 CMake defines the option CMAKE_BUILD_TYPE which can be set to "Debug",
365 "Release", "RelWithDebInfo", "MinSizeRel", or it can be empty. (See the CMake
366 documentation for more details.) By default CMAKE_BUILD_TYPE is empty. In
367 short, while developing code or debugging, the value of "Debug" or
368 "RelWithDebInfo" should be used. When building for production runs one of the
369 other values should be used.
370
371 D.2.3 INSTALLATION PREFIX
372
373 Here and below, all paths or filepaths must be specified in a format
374 appropriate for the OS (windows or linux). Windows paths are of the form
375 C:\dir1\dir2 (forward slashes may be used instead to avoid escaping issues:
376 C:/dir1/dir2) and linux paths are of the form /dir1/dir2.
377
378 By default CMake installs the KIM API package under the Global prefix
379 "/usr/local". This is referred to as a "Global" (or system-wide) installation.
380 It is available to all users of the system. (Other "Global" prefix values are
381 "/" and "/usr".) However, such installations require root user permissions (as
382 implied by the use of the "sudo" command above). If you do not have root user
383 permission and/or do not want to install the KIM API to the global location,
384 you can change where CMake installs the KIM API by replacing the command (from
385 above)
386
387  $cmake .. -DCMAKE_BUILD_TYPE=Release 388 389 with 390 391$ cmake .. -DCMAKE_INSTALL_PREFIX="/install/prefix/path" -DCMAKE_BUILD_TYPE=Release
392
393 where "/install/prefix/path" should be replaced with your desired prefix. For
394 example, to install the KIM API in the "local" subdirectory of your home
395 directory, use "${HOME}/local". When installed in such a directory, the user 396 may employ the "kim-api-activate" utility to setup the PATH and bash 397 completions. For example: 398 399$ source ${HOME}/local/bin/kim-api-activate 400 401 D.2.4 KIM API SPECIFIC BUILD OPTIONS 402 403 The KIM API defines two additional regular build options and additional 404 advanced options. 405 406 * KIM_API_LOG_MAXIMUM_LEVEL (="DEBUG" if CMAKE_BUILD_TYPE is "Debug", otherwise 407 ="INFORMATION") This option takes one of the following six values "SILENT", 408 "FATAL", "ERROR", "WARNING", "INFORMATION", "DEBUG". This value controls, at 409 compile-time, which type of log messages can be printed to the "kim.log" 410 file. 411 412 * KIM_API_BUILD_EXAMPLES (=ON) When ON CMake will build the example MDs, PMs, 413 SMs and Simulators. NOTE: this option may be removed/changed in future 414 releases when the examples are incorporated into the documentation. 415 416 Additionally, the KIM API defines the following advanced build options. 417 418 * KIM_API_PROJECT_NAME (="kim-api") This value controls the naming of many 419 aspects of the package build. Generally this should not be changed. It can 420 be used to build and install, on the same machine, two different copies 421 (typically different versions) of the package. 422 423 * KIM_API_ENABLE_SANITIZE (=OFF) When ON this enables the AddressSanitizer 424 library for detecting memory corruption bugs. 425 426 * KIM_API_ENABLE_COVERAGE (=OFF) When ON this enables gcov code coverage. 427 428 * KIM_API_CONFIGURATION_TIMESTAMP (=<utc-time-of-cmake-configuration>) This is 429 used as part of the <kim-api-uid> universal ID for the kim-api installation. 430 431 * KIM_API_CMAKE_C_COMPILER (="${CMAKE_C_COMPILER}") This value is recorded and
432  used after installation for compilation of items (MDs, PMs, SMs, etc.) to
433  ensure binary compatibility with the installed KIM API.
434
435 * KIM_API_CMAKE_CXX_COMPILER (="${CMAKE_CXX_COMPILER}") This value is recorded 436 and used after installation for compilation of items (MDs, PMs, SMs, etc.) 437 to ensure binary compatibility with the installed KIM API. 438 439 * KIM_API_CMAKE_Fortran_COMPILER (="${CMAKE_Fortran_COMPILER}") This value is
440  recorded and used after installation for compilation of items (MDs, PMs, SMs,
441  etc.) to ensure binary compatibility with the installed KIM API.
442
443 * KIM_API_USER_CONFIGURATION_FILE (=".${PROJECT_NAME}/config") This value 444 determines the default name of the KIM API user configuration file. If the 445 value corresponds to a relative path (does not start with "/"), then it is 446 interpreted as relative to the user's home directory "${HOME}".
447
448 * KIM_API_USER_MODEL_DRIVERS_DIR_DEFAULT
449  (="~/.${PROJECT_NAME}/<kim-api-uid>/model-drivers") This value specifies the 450 default colon ':' (semicolon ';' on windows) separated list of the MD 451 directory locations for the user collection. 452 453 * KIM_API_USER_PORTABLE_MODELS_DIR_DEFAULT 454 (="~/.${PROJECT_NAME}/<kim-api-uid>/portable-drivers") This value specifies
455  the default colon ':' (semicolon ';' on windows) separated list of the PM
456  directory locations for the user collection.
457
458 * KIM_API_USER_SIMULATOR_MODELS_DIR_DEFAULT
459  (="~/.${PROJECT_NAME}/<kim-api-uid>/simulator-models") This value specifies 460 the default colon ':' (semicolon ';' on windows) separated list of the SM 461 directory locations for the user collection. 462 463 * KIM_API_SYSTEM_MODEL_DRIVERS_DIR 464 (="${CMAKE_INSTALL_FULL_LIBDIR}/${PROJECT_NAME}/model-drivers") This value 465 specifies a colon ':' (semicolon ';' on windows) separated list of the MD 466 directory locations in the system collection. If the value starts with a 467 colon (semicolon on windows), cmake will update it by prepending the default 468 value. 469 470 * KIM_API_SYSTEM_PORTABLE_MODELS_DIR 471 (="${CMAKE_INSTALL_FULL_LIBDIR}/${PROJECT_NAME}/portable-models") This value 472 specifies a colon ':' (semicolon ';' on windows) separated list of the PM 473 directory locations in the system collection. If the value starts with a 474 colon (semicolon on windows), cmake will update it by prepending the default 475 value. 476 477 * KIM_API_SYSTEM_SIMULATOR_MODELS_DIR 478 (="${CMAKE_INSTALL_FULL_LIBDIR}/${PROJECT_NAME}/simulator-models") This value 479 specifies a colon ':' (semicolon ';' on windows) separated list of the SM 480 directory locations in the system collection. If the value starts with a 481 colon (semicolon on windows), cmake will update it by prepending the default 482 value. 483 484 D.3 Installing multiple versions 485 486 On linux and macOS systems if you intend to install multiple versions of the 487 KIM API using the same installation prefix 488 ("-DCMAKE_INSTALL_PREFIX=/install/prefix/path" argument to cmake) you must take 489 care that the installations do not overwrite each other. If you intend to 490 install multiple versions using the same prefix you must use the 491 "-DKIM_API_PROJECT_NAME=project-name" argument (See D.2.4 above) to cmake and 492 use a unique value (any string without whitespace or control characters is 493 valid) for each installation. 494 495 Full support for the "-DKIM_API_PROJECT_NAME" argument, as described here, was 496 first available in v2.0.2. For example, suppose the current version of the KIM 497 API were v3.2.1, and you want to also install KIM API v3.0.0, and v2.1.1. 498 Then, you would configure each version as follows: 499 500 * v3.2.1 501 502$ cmake .. [additional args] # use default ("kim-api") for current version.
503
504  * v3.0.0
505
506  $cmake .. -DKIM_API_PROJECT_NAME=kim-api3.0 [additional args] 507 508 * v2.1.1 509 510$ cmake .. -DKIM_API_PROJECT_NAME=kim-api2.1 [additional args]
511
512 D.4 Uninstall the KIM API
513
514 When the KIM API package is installed, CMake creates a file in the build tree
515 named "install_manifest.txt". For the above commands this file would be
516 located at "${HOME}/kim-api-X.Y.Z/build/install_manifest.txt". The manifest 517 file contains the absolute file name of every file installed as part of the KIM 518 API package. The contents of the install_manifest.txt file can be used to 519 remove these files and, thus, uninstall the KIM API package. Thus, the 520 install_manifest.txt file should be saved for later use, if necessary. 521 522 For example, the following commands could be used to uninstall the KIM API 523 package (assuming the "install_manifest.txt" file is located in your home 524 directory). 525 526$ cd "${HOME}" 527$ while read line || test -n "${line}"; do sudo rm -f "${line}"; done < install_manifest.txt
528
529 A more sophisticated set of commands could also remove any empty subdirectories
530 left behind by this process.
531
532 It may also be desirable to remove the user configuration file and user
533 collection directories.
534
535  $rm -rf "${HOME}/.kim-api"
536
537
538 -------------------------------------------------------------------------------
539
540 E. ADDING MDs, PMs, and SMs TO THE COLLECTIONS
541
542
543 Here we describe how to add MDs, PMs, and SMs to the system-collection,
544 user-collection, environment-variable-collection, and the CWD-collection.
545
546 E.1 ADDING MDs, PMs, and SMs TO THE SYSTEM-COLLECTION
547
548 Once you have the KIM API installed, it is easy to add additional MDs, PMs, and
549 SMs to the system-collection.
550
551 $cd "${WORKSPACE}"
552
553 $kim-api-collections-management install system --sudo Morse_Shifted_Jelinek_1972_Ar__MO_831902330215_003 554$ kim-api-collections-management install system --sudo Sim_LAMMPS_ADP_PunDarlingKecskes_2015_CuTa__SM_399364650444_000
555
556 The kim-api-collections-management utility automatically installs the necessary
557 MD too. You can see the items in the various collections by executing the
558 following command.
559
560 $kim-api-collections-management list 561 562 Now we can test the newly installed PM. 563 564$ cd "${WORKSPACE}/utility_forces_numer_deriv/build" # we'll assume this is already built 565$ printf "Morse_Shifted_Jelinek_1972_Ar__MO_831902330215_003" | ./utility_forces_numer_deriv
566
567 E.2 ADDING MDs, PMs, and SMs TO THE USER-COLLECTION
568
569 Adding MDs, PSs, and SMs to the user-collection is similar.
570
571 $cd "${WORKSPACE}"
572
573 $kim-api-collections-management install user LJ_Shifted_Bernardes_1958HighCutoff_Ar__MO_242741380554_003 574$ kim-api-collections-management install user Sim_LAMMPS_AGNI_BotuBatraChapman_2017_Al__SM_666183636896_000
575 $kim-api-collections-management list 576$ cd "${WORKSPACE}/utility_forces_numer_deriv/build" # we'll assume this is already built 577$ printf "LJ_Shifted_Bernardes_1958HighCutoff_Ar__MO_242741380554_003" | ./utility_forces_numer_deriv
578
579 E.3 ADDING MDs, PMs, and SMs TO THE ENVIRONMENT-VARIABLE-COLLECTION
580
581 Adding MDs, PMs, and SMs to the environment-variable-collection is similar.
582
583 $cd "${WORKSPACE}"
584
585 $mkdir -p "${WORKSPACE}/my-env-collection/model-drivers"
586 $export KIM_API_MODEL_DRIVERS_DIR="${WORKSPACE}/my-env-collection/model-drivers"
587 $mkdir -p "${WORKSPACE}/my-env-collection/portable-models"
588 $export KIM_API_PORTABLE_MODELS_DIR="${WORKSPACE}/my-env-collection/portable-models"
589 $mkdir -p "${WORKSPACE}/my-env-collection/simulator-models"
590 $export KIM_API_SIMULATOR_MODELS_DIR="${WORKSPACE}/my-env-collection/simulator-models"
591 $kim-api-collections-management install environment Morse_Shifted_GirifalcoWeizer_1959HighCutoff_Cu__MO_151002396060_003 592$ kim-api-collections-management install environment Sim_LAMMPS_BOP_WardZhouWong_2012_CdZnTe__SM_409035133405_000
593 $kim-api-collections-management list 594$ cd "${WORKSPACE}/utility_forces_numer_deriv/build" # we'll assume this is already built 595$ printf "Morse_Shifted_GirifalcoWeizer_1959HighCutoff_Cu__MO_151002396060_003" | ./utility_forces_numer_deriv
596
597 E.4 ADDING MDs, PMs, and SMs TO THE CWD-COLLECTION
598
599 Adding MDs, PMs, and SMs to the CWD-collection is, again, similar.
600
601 $cd "${WORKSPACE}"
602
603 $kim-api-collections-management install CWD Exp6_KongChakrabarty_1973_ArNe__MO_946046425752_002 604$ kim-api-collections-management install CWD Sim_LAMMPS_MEAM_EtesamiAsadi_2018_Ni__SM_333792531460_000
605 $kim-api-collections-management list 606$ printf "Exp6_KongChakrabarty_1973_ArNe__MO_946046425752_002" | "${WORKSPACE}/utility_forces_numer_deriv/build/utility_forces_numer_deriv" # we'll assume this is already built 607 608 E.5 Adding MDs, PMs, and SMs from a local source directory 609 610 The kim-api-collections-management utility allows for the installation of items 611 from a directory on the local file system. This is useful if you are 612 developing an item or do not have network access to openkim.org, but already 613 have the source code downloaded. We'll assume that the item's source code 614 (including the CMakeLists.txt file, parameter files, etc) you want to install 615 are in directory "${WORKSPACE}/item-source". Then you simply provide this
616 directory name instead of the item name.
617
618  $kim-api-collections-management install user "${WORKSPACE}/item-source"
619
620 E.6 Manually adding MDs, PMs, and SMs
621
622 If necessary a MD, PM, or SM may be manually built and installed. We'll assume
623 the item's source code is in the current directory
624
625  $mkdir build 626$ cd build
627  $cmake .. -DKIM_API_INSTALL_COLLECTION=SYSTEM 628$ make
629  \$ sudo make install
630
631 The KIM_API_INSTALL_COLLECTION variable can also take values USER and
632 ENVIRONMENT.
633
634 *******************************************************************************
635
636 SUPPORT
637
638 Support is always available by posting questions with all relevant information
639 to
640
641 <https://matsci.org/openkim>
642
643 Members of the OpenKIM development team actively monitor this forum and
644 will do their best to respond to questions in a timely fashion.
645
646 *******************************************************************************