kim-api 2.4.1+AppleClang.AppleClang.GNU
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
 
Loading...
Searching...
No Matches
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.
4# All rights reserved.
5#
6# Contributors:
7# Ryan S. Elliott
8# Ellad B. Tadmor
9#
10# SPDX-License-Identifier: LGPL-2.1-or-later
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
14# License as published by the Free Software Foundation; either
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-2.4.1 package.
29#
30
31
32============================= The KIM API package =============================
33
34This file contains instructions for installing the KIM API package.
35
36
37TABLE OF CONTENTS
38
39A. System requirements
40
41B. Quick start
42
43C. 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
53D. 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
63E. 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
74A. SYSTEM REQUIREMENTS
75
76
77To install and run the KIM API package you need the following:
78
791. A Unix/Linux/macOS system.
80
812. CMake (3.10 or later).
82
833. 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
874. wget or curl, sed, grep, tar, uname, etc. (used by the
88 kim-api-collections-management utility).
89
905. Doxygen and Graphviz (for generating the documentation).
91
926. The bash-completion package (for facilitating command-line usage of the
93 helper utilities).
94
957. pkg-config can be used by code needing to link against the kim-api library.
96
97
98-------------------------------------------------------------------------------
99
100B. QUICK START: For those who don't like to read and are a bit audacious.
101
102Try the following:
103
104 $ mkdir build && cd build
105 $ cmake .. -DCMAKE_BUILD_TYPE=Release
106 $ make
107 $ sudo make install
108 $ sudo ldconfig
109
110For more information, see section D.
111
112-------------------------------------------------------------------------------
113
114C. PACKAGE LAYOUT AND OPERATION OVERVIEW
115
116
117The KIM API package is a system-level library that aims to give computer
118programmers the ability to write atomistic or molecular simulation programs
119(Simulators) that can seamlessly interface with implementations of interatomic
120potentials (Portable Models, PMs), regardless of the programming language in
121which the codes are written. The KIM API package provides a dedicated Portable
122Model Interface (PMI) for use by simulators and PMs and referred to as the KIM
123API/PMI. A PM can include code and parameters all in one. Or, a PM can
124include just parameters and use a separate Model Driver (MD) library containing
125the code. There are also Simulator Models (SMs) that only work with a specific
126simulator. The KIM API package provides a dedicated Simulator Model Interface
127(SMI) for use by simulators and SMs and referred to as the KIM API/SMI. In
128addition to the main KIM API library, a small number of associated helper
129utilities are provided.
130
131C.1. KIM API Library
132
133The KIM API library provides the necessary routines for a Simulator to interact
134with a PM or SM. It also contains an interface for discovering what MDs, PMs,
135and SMs are available in the KIM API Collections. MDs, PMs, and SMs are built
136and linked against the KIM API library, then installed in one of the
137collections (see below) so that they are available for use with a simulator.
138Simulators are built and linked against the KIM API library so that they can
139access and use any of the available PMs and/or SM in the various collections.
140
141C.2 COLLECTIONS FOR MODEL DRIVERS (MDs), PORTABLE MODELS (PMs), AND
142 SIMULATOR MODELS (SMs)
143
144The KIM API supports four Collections of Items. These are the
145"system-collection", the "user-collection", the
146"environment-variable-collection", and the "CWD-collection" as described below.
147Each collection consists of separate sets of three Item Types: MDs, PMs, and
148SMs. When the KIM API needs to use a particular MD, PD, or SM, it looks for
149the item by type and name, first in the CWD-collection, then in the
150environment-variable-collection, then in the user-collection, and finally in
151the system-collection. It uses the first match that it finds. Note, it is
152possible for a PM and its associated MD to be located in different collections.
153The search for each is a separate and independent procedure.
154
155See also the documentation for the Collections Interface (c++:
156KIM::Collections; c: KIM_Collections; and Fortran: kim_collections_module).
157
158C.2.1 THE SYSTEM-COLLECTION
159
160The system-collection is a collection of MDs, PMs, and SMs that are available
161to all simulators that use the KIM API library. By default, this collection is
162located in the same subdirectory as the KIM API library. (See also the
163"KIM_API_SYSTEM_*_DIR" build options in section D.2.4, below.)
164
165MDs, PMs, and SMs may be built and installed to the system-collection at
166anytime after the KIM API has been built and installed.
167
168C.2.2 THE USER-COLLECTION
169
170The user-collection is a collection of MDs, PMs, and SMs that are available
171only to the user who owns the process for the simulator that uses the KIM API
172library. This collection is located in subdirectories that are specified by a
173configuration file. The user-collection may be populated with MDs, PMs, and
174SMs after the KIM API has been built and installed.
175
176The configuration file is named "${HOME}/.kim-api/<kim-api-uid>/config" by
177default, where <kim-api-uid> is a unique identifier for the particular
178installation of the kim-api being used (this allows multiple, independent,
179installations on a single machine). Here "${HOME}" is the user's home
180directory. (See item D below for build options controlling this default file
181name.) If the "KIM_API_CONFIGURATION_FILE" environment variable is set, its
182value (interpreted as an absolute file name) will supersede the default
183location and name of the configuration file. For example, the following
184commands will instruct the KIM API library to use a file named "kim-config" in
185the /my-kim-stuff folder
186
187 $ export KIM_API_CONFIGURATION_FILE=/my-kim-stuff/kim-config
188
189If the configuration file does not exist, the KIM API library will create it
190with a default configuration specifying that the user-collection files are
191stored in "${HOME}/.kim-api/<kim-api-uid>/model-drivers/",
192"${HOME}/.kim-api/<kim-api-uid>/portable-models/", and
193"${HOME}/.kim-api/<kim-api-uid>/simulator-models/". More generally, the values
194in the configuration file may contain colon ':' (on Windows: semi-colon ';')
195separated lists of fully-qualified directory names (starting, strictly, with
196'/', '~/' or a root drive letter like 'C:/'). (See item D below for build
197options controlling these defaults.)
198
199C.2.3 THE ENVIRONMENT-VARIABLE-COLLECTION
200
201The environment-variable-collection is a collection of MDs, PMs, and SMs that
202are specified by the run-time environment of the process for the simulator that
203uses the KIM API library. The locations of this collection are specified by
204the environment variables "KIM_API_MODEL_DRIVERS_DIR",
205"KIM_API_PORTABLE_MODELS_DIR", and "KIM_API_SIMULATOR_MODELS_DIR". These
206variables should contain colon ':' (on Windows: semi-colon ';') separated lists
207of absolute directory names where the collection MDs, PMs, and SMs, respectively,
208are located. (For example, in bash you could execute the command
209
210 $ export KIM_API_PORTABLE_MODELS_DIR=/my-kim-stuff/models-i-am-developing:/my-kim-stuff/misc-portable-models
211
212to have the KIM API look for PMs in /my-kim-stuff/models-i-am-developing first
213and then look in /my-kim-stuff/misc-portable-models. (Similarly for MDs and
214SMs.) The environment-variable-collection may be populated with MDs, PMs, and
215SMs after the KIM API has been built and installed.
216
217C.2.4 THE CWD-COLLECTION
218
219The CWD-collection is a collection of MDs, PMs, SMs that are available to a
220simulator at run-time. The collection is located in the simulator process's
221current working directory (CWD). The CWD-collection may be populated with MDs,
222PMs, and SMs after the KIM API has been built and installed.
223
224C.3 HELPER UTILITIES
225
226The KIM API package also includes a utility for managing the MDs, PMs, and SMs
227contained in the various collections and for managing the configuration file.
228This utility is called "kim-api-collections-management". The KIM API package
229installs bash completion scripts that are designed to work with the
230"bash-completion" package (https://github.com/scop/bash-completion). When
231"bash-completion" is installed and activated on the system, tab-completions for
232the collections management utility should be automatically loaded and available
233for use.
234
235In addition, when the KIM API package is installed to a "Local (non-global)"
236(see D below) directory, the package also installs the "kim-api-activate" and
237"kim-api-deactivate" scripts. The activate script adds the utilities to the
238executable PATH, adds the KIM API library to the PKG_CONFIG_PATH so that the
239pkg-config utility can find it, and loads bash tab-completion support for the
240collections management utility. The deactivate script removes what the
241activate script added.
242
243
244-------------------------------------------------------------------------------
245
246D. KIM API INSTALLATION
247
248D.1 Typical Build Scenario
249
250Here, the typical KIM API build and install process is detailed and the
251system-collection is populated with the example MDs, PMs, and SMs, as well as a
252single PM and its associated MD, both from openkim.org. Additionally, one of
253the example simulators is copied to the user's home directory and used to test
254the KIM API. The KIM API package uses the CMake build system. See the CMake
255documentation (https://cmake.org/cmake/help/v3.10/) for help with CMake
256settings. For some common CMake settings and KIM API specific settings, see
257D.2 below.
258
259The commands given below are for the bash shell.
260
261By default packages are installed to the Global prefix directory "/usr/local".
262Here we assume that "/usr/local/bin" is included as part of the system's
263standard PATH setting.
264
265First, we will create a working space and obtain the source package
266
267 $ export WORKSPACE="${HOME}/kim-api-workspace"
268 $ mkdir "${WORKSPACE}"
269 $ cd "${WORKSPACE}
270 $ wget https://s3.openkim.org/kim-api/kim-api-X.Y.Z.txz # replace X, Y, and Z with the current version numbers
271 $ tar Jxvf kim-api-X.Y.Z.txz
272 $ cd kim-api-X.Y.Z
273
274We will set an environment variable to point the the KIM API source.
275
276 $ export KIM_API_SOURCE="${WORKSPACE}/kim-api-X.Y.Z" # replace X, Y, and Z with the current version numbers
277
278Next the configuration and build process begins. (Note: lines beginning with
279"$", without leading whitespace, in this file are extracted and used in the KIM
280API automated Continuous-Integration (CI) testing framework.)
281
282$ cd "${WORKSPACE}"
283$ mkdir build
284$ cd build
285$ cmake ${KIM_API_SOURCE} -DCMAKE_BUILD_TYPE=Release
286$ make -j2
287
288If you want, build the documentation.
289
290$ make docs
291
292If you want, before installing the package, you can run the tests.
293
294$ make test
295
296Now, install the package (and docs, if built).
297
298$ sudo make install
299$ 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
300$ cp -r "${KIM_API_SOURCE}/examples/simulators/utility_forces_numer_deriv" "${WORKSPACE}/"
301$ cd "${WORKSPACE}"
302
303If you want, you can now delete the source and build tree. However, you may
304also want to preserve the "install_manifest.txt" file which would be needed for
305uninstalling the KIM API package (see D.4 below).
306
307 $ cp "${WORKSPACE}/build/install_manifest.txt" "${WORKSPACE}/install_manifest.txt"
308 $ rm -r "${WORKSPACE}/build
309
310Now, we can build the simulator using the KIM API library that we have just
311installed.
312
313$ cd utility_forces_numer_deriv
314$ mkdir build
315$ cd build
316$ cmake ..
317$ make
318
319Try it with one of the example models:
320
321$ printf "ex_model_Ar_P_LJ" | ./utility_forces_numer_deriv
322
323Next, we can try it with a model installed from https://openkim.org:
324
325$ kim-api-collections-management install system --sudo EDIP_JustoBazantKaxiras_1998_Si__MO_958932894036_002
326$ printf "EDIP_JustoBazantKaxiras_1998_Si__MO_958932894036_002" | ./utility_forces_numer_deriv
327
328Congratulations, you have now successfully installed the KIM API. If you would
329like to learn more about the KIM API, read the documentation in the docs
330directory (/usr/local/share/doc/kim-api).
331
332If you would like to install the latest release of all models from
333https://openkim.org, you can do:
334
335 $ kim-api-collections-management install system --sudo OpenKIM
336
337D.2 CMAKE BUILD OPTIONS
338
339The KIM API defines a number of specific build options which are detailed in
340this section. But first, some notes about a few important standard CMake
341options.
342
343D.2.1 COMPILER SELECTION
344
345By default CMake will search for appropriate compilers available on your
346system. Generally, it selects reasonable choices. However, if you wish to
347force CMake to use specific compilers, you can do so with environment variables
348set on the command line. For example, suppose you have the latest GNU Compiler
349Collection (GCC) version X installed with the compilers named 'gcc-X', 'g++-X',
350and 'gfortran-X', for the C, C++, and Fortran compilers, respectively. Then,
351to force CMake to use these compilers, replace the command (from above)
352
353 $ cmake .. -DCMAKE_BUILD_TYPE=Release
354
355with
356
357 $ CC=gcc-X CXX=g++-X FC=gfortran-X cmake .. -DCMAKE_BUILD_TYPE=Release
358
359D.2.2 CMAKE_BUILD_TYPE
360
361CMake defines the option CMAKE_BUILD_TYPE which can be set to "Debug",
362"Release", "RelWithDebInfo", "MinSizeRel", or it can be empty. (See the CMake
363documentation for more details.) By default CMAKE_BUILD_TYPE is empty. In
364short, while developing code or debugging, the value of "Debug" or
365"RelWithDebInfo" should be used. When building for production runs one of the
366other values should be used.
367
368D.2.3 INSTALLATION PREFIX
369
370Here and below, all paths or filepaths must be specified in a format
371appropriate for the OS (windows or linux). Windows paths are of the form
372C:\dir1\dir2 (forward slashes may be used instead to avoid escaping issues:
373C:/dir1/dir2) and linux paths are of the form /dir1/dir2.
374
375By default CMake installs the KIM API package under the Global prefix
376"/usr/local". This is referred to as a "Global" (or system-wide) installation.
377It is available to all users of the system. (Other "Global" prefix values are
378"/" and "/usr".) However, such installations require root user permissions (as
379implied by the use of the "sudo" command above). If you do not have root user
380permission and/or do not want to install the KIM API to the global location,
381you can change where CMake installs the KIM API by replacing the command (from
382above)
383
384 $ cmake .. -DCMAKE_BUILD_TYPE=Release
385
386with
387
388 $ cmake .. -DCMAKE_INSTALL_PREFIX="/install/prefix/path" -DCMAKE_BUILD_TYPE=Release
389
390where "/install/prefix/path" should be replaced with your desired prefix. For
391example, to install the KIM API in the "local" subdirectory of your home
392directory, use "${HOME}/local". When installed in such a directory, the user
393may employ the "kim-api-activate" utility to setup the PATH and bash
394completions. For example:
395
396 $ source ${HOME}/local/bin/kim-api-activate
397
398D.2.4 KIM API SPECIFIC BUILD OPTIONS
399
400The KIM API defines two additional regular build options and additional
401advanced options.
402
403* KIM_API_LOG_MAXIMUM_LEVEL (="DEBUG" if CMAKE_BUILD_TYPE is "Debug", otherwise
404 ="INFORMATION") This option takes one of the following six values "SILENT",
405 "FATAL", "ERROR", "WARNING", "INFORMATION", "DEBUG". This value controls, at
406 compile-time, which type of log messages can be printed to the "kim.log"
407 file.
408
409* KIM_API_BUILD_EXAMPLES (=ON) When ON CMake will build the example MDs, PMs,
410 SMs and Simulators. NOTE: this option may be removed/changed in future
411 releases when the examples are incorporated into the documentation.
412
413Additionally, the KIM API defines the following advanced build options.
414
415* KIM_API_PROJECT_NAME (="kim-api") This value controls the naming of many
416 aspects of the package build. Generally this should not be changed. It can
417 be used to build and install, on the same machine, two different copies
418 (typically different versions) of the package.
419
420* KIM_API_BASE64_BUFFERSIZE (="16777216") Sets the buffer size for the C++
421 base64 encode/decode routines used in the kim-api.
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
484D.3 Installing multiple versions
485
486On linux and macOS systems if you intend to install multiple versions of the
487KIM API using the same installation prefix
488("-DCMAKE_INSTALL_PREFIX=/install/prefix/path" argument to cmake) you must take
489care that the installations do not overwrite each other. If you intend to
490install 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
492use a unique value (any string without whitespace or control characters is
493valid) for each installation.
494
495Full support for the "-DKIM_API_PROJECT_NAME" argument, as described here, was
496first available in v2.0.2. For example, suppose the current version of the KIM
497API were v3.2.1, and you want to also install KIM API v3.0.0, and v2.1.1.
498Then, 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
512D.4 Uninstall the KIM API
513
514When the KIM API package is installed, CMake creates a file in the build tree
515named "install_manifest.txt". For the above commands this file would be
516located at "${HOME}/kim-api-X.Y.Z/build/install_manifest.txt". The manifest
517file contains the absolute file name of every file installed as part of the KIM
518API package. The contents of the install_manifest.txt file can be used to
519remove these files and, thus, uninstall the KIM API package. Thus, the
520install_manifest.txt file should be saved for later use, if necessary.
521
522For example, the following commands could be used to uninstall the KIM API
523package (assuming the "install_manifest.txt" file is located in your home
524directory).
525
526 $ cd "${HOME}"
527 $ while read line || test -n "${line}"; do sudo rm -f "${line}"; done < install_manifest.txt
528
529A more sophisticated set of commands could also remove any empty subdirectories
530left behind by this process.
531
532It may also be desirable to remove the user configuration file and user
533collection directories.
534
535 $ rm -rf "${HOME}/.kim-api"
536
537
538-------------------------------------------------------------------------------
539
540E. ADDING MDs, PMs, and SMs TO THE COLLECTIONS
541
542
543Here we describe how to add MDs, PMs, and SMs to the system-collection,
544user-collection, environment-variable-collection, and the CWD-collection.
545
546E.1 ADDING MDs, PMs, and SMs TO THE SYSTEM-COLLECTION
547
548Once you have the KIM API installed, it is easy to add additional MDs, PMs, and
549SMs 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
556The kim-api-collections-management utility automatically installs the necessary
557MD too. You can see the items in the various collections by executing the
558following command.
559
560$ kim-api-collections-management list
561
562Now 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
567E.2 ADDING MDs, PMs, and SMs TO THE USER-COLLECTION
568
569Adding 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
579E.3 ADDING MDs, PMs, and SMs TO THE ENVIRONMENT-VARIABLE-COLLECTION
580
581Adding 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
597E.4 ADDING MDs, PMs, and SMs TO THE CWD-COLLECTION
598
599Adding 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
608E.5 Adding MDs, PMs, and SMs from a local source directory
609
610The kim-api-collections-management utility allows for the installation of items
611from a directory on the local file system. This is useful if you are
612developing an item or do not have network access to openkim.org, but already
613have 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
615are in directory "${WORKSPACE}/item-source". Then you simply provide this
616directory name instead of the item name.
617
618 $ kim-api-collections-management install user "${WORKSPACE}/item-source"
619
620E.6 Manually adding MDs, PMs, and SMs
621
622If necessary a MD, PM, or SM may be manually built and installed. We'll assume
623the 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
631The KIM_API_INSTALL_COLLECTION variable can also take values USER and
632ENVIRONMENT.
633
634*******************************************************************************
635
636SUPPORT
637
638Support is always available by posting questions with all relevant information
639to
640
641<https://matsci.org/openkim>
642
643Members of the OpenKIM development team actively monitor this forum and
644will do their best to respond to questions in a timely fashion.
645
646*******************************************************************************