#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the Common Development
# and Distribution License Version 1.0 (the "License").
#
# You can obtain a copy of the license at
# http://www.opensource.org/licenses/CDDL-1.0.  See the License for the
# specific language governing permissions and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each file and
# include the License file in a prominent location with the name LICENSE.CDDL.
# If applicable, add the following below this CDDL HEADER, with the fields
# enclosed by brackets "[]" replaced with your own identifying information:
#
# Portions Copyright (c) [yyyy] [name of copyright owner]. All rights reserved.
#
# CDDL HEADER END
#

#
# Copyright (c) 2013--2019, Regents of the University of Minnesota.
# All rights reserved.
#
# Contributors:
#    Ryan S. Elliott
#    Ellad B. Tadmor
#

#
# Release: This file is part of the kim-api-2.0.2 package.
#


============================= The KIM API package =============================

This file contains instructions for installing the KIM API package.


TABLE OF CONTENTS

A. System requirements

B. Quick start

C. Package concepts and operation overview
   C.1 KIM API library
   C.2 Model Drivers (MDs), Models (MOs), and Simulator Models (SMs) collections
       C.2.1 The system-collection
       C.2.2 The user-collection
       C.2.3 The environment-variable-collection
       C.2.4 The CWD-collection
   C.3 Helper utilities

D. KIM API Installation
   D.1 Typical build scenario
   D.2 CMake build options
       D.2.1 Compiler selection
       D.2.2 CMAKE_BUILD_TYPE
       D.2.3 Installation prefix
       D.2.4 KIM API specific build options
   D.3 Installing multiple versions
   D.4 Uninstall the KIM API

E. Adding MDs, MOs, and SMs to the collections
   E.1 Adding MDs, MOs, and SMs to the system-collection
   E.2 Adding MDs, MOs, and SMs to the user-collection
   E.3 Adding MDs, MOs, and SMs to the environment-variable-collection
   E.4 Adding MDs, MOs, and SMs to the CWD-collection
   E.5 Manually adding MDs, MOs, and SMs


-------------------------------------------------------------------------------

A. SYSTEM REQUIREMENTS


To install and run the KIM API package you need the following:

1. A Unix/Linux/macOS system.

2. CMake (3.4 or later).  (CMake 3.9 or later is required for building the
   Doxygen documentation.)

3. GNU compilers (gcc, g++, gfortran) version 4.8.x or higher or the
   corresponding Intel compilers, version 11.1 or higher.  Other compilers may
   also work.

4. The 'xxd' utility (distributed as part of the vim package).

5. wget and tar (used by the kim-api-collections-management utility).

6. Doxygen and Graphviz (for generating the documentation).

7. The bash-completion package (for facilitating command-line usage of the
   helper utilities).

8. pkg-config can be used by code needing to link against the kim-api library.


-------------------------------------------------------------------------------

B. QUICK START: For those who don't like to read and are a bit audacious.

Try the following:

$ mkdir build && cd build
$ cmake .. -DCMAKE_BUILD_TYPE=Release
$ make
$ sudo make install
$ sudo ldconfig

For more information, see section D.

-------------------------------------------------------------------------------

C. PACKAGE LAYOUT AND OPERATION OVERVIEW


The KIM API package is a system-level library that aims to give computer
programmers the ability to write atomistic or molecular simulation programs
(Simulators) that can seamlessly interface with implementations of interatomic
potential (Models), regardless of the programming language in which the codes
are written.  Models can be "stand-alone", corresponding to code and parameters
all in one.  Or, Models can be "parameterized", corresponding to just a set of
parameters that must be connected to a Model Driver which contains the code
that can be used with any set of parameters.  There are also Simulator Models
that are similar to parameterized models, but must be used with a specific
simulator.  In addition to the main KIM API library, a small number of
associated helper utilities are provided.

C.1. KIM API Library

The KIM API library provides the necessary routines for a Model and a Simulator
to interact.  Models and Simulator Models are built and linked against the KIM
API library, then installed in one of the model collections (see below) so that
they are available for use with a Simulator.  Simulators are built and linked
against the KIM API library so that they can access and use any of the
available Models or Simulator Models in the various collections.

C.2 MODEL DRIVERS (MDs), MODELS (MOs), AND SIMULATOR MODELS (SMs) COLLECTIONS

The KIM API supports four "collections" of Model Drivers, Models, and Simulator
Models.  These are the "system-collection", the "user-collection", the
"environment-variable-collection", and the "CWD-collection" as described below.

When the KIM API needs to use a particular Model Driver or Model, it looks for
the item by name, first in the CWD-collection, then in the
environment-variable-collection, then in the user-collection, and finally in
the system-collection.  It uses the first match that it finds.  Note, it is
possible for a (parameterized) Model and its Driver to be located in different
collections.  The search for each is a separate and independent procedure.

C.2.1 THE SYSTEM-COLLECTION

The system-collection is a collection of Model Drivers, Models, and Simulator
Models that are available to all Simulators that use the KIM API library.  By
default, this collection is located in the same subdirectory as the KIM API
library.  (See also the "KIM_API_SYSTEM_*_DIR" build options in section D.2.4,
below.)

Model Drivers, Models, and Simulator Models may be built and installed to the
system-collection at anytime after the KIM API has been built and installed.

C.2.2 THE USER-COLLECTION

The user-collection is a collection of Model Drivers, Models, and Simulator
Models that are available only to the user who owns the process for the
Simulator that uses the KIM API library.  This collection is located in
subdirectories that are specified by a configuration file.  The user-collection
may be populated with Model Drivers, Models, and Simulator Models after the KIM
API has been built and installed.

The configuration file is named "${HOME}/.kim-api/config" by default.  Here
"${HOME}" is the user's home directory.  (See item D below for build options
controlling this default file name.)  If the "KIM_API_CONFIGURATION_FILE"
environment variable is set, its value (interpreted as an absolute file name)
will supersede the default location and name of the configuration file.  If
this file does not exist, the KIM API library will create it with a default
configuration specifying that the user-collection files are stored in
"${HOME}/.kim-api/model-drivers/" and "${HOME}/.kim-api/models/".  More
generally, the values in the configuration file may contain colon ':' separated
lists of directory names (starting, strictly, with '/' or '~/').

C.2.3 THE ENVIRONMENT-VARIABLE-COLLECTION

The environment-variable-collection is a collection of Model Drivers, Models,
and Simulator Models that are specified by the run-time environment of the
process for the Simulator that uses the KIM API library.  The locations of this
collection are specified by the environment variables
"KIM_API_MODEL_DRIVERS_DIR", "KIM_API_MODELS_DIR", and
"KIM_API_SIMULATOR_MODELS_DIR".  These variables should contain colon ':'
separated lists of absolute directory names where the collection Model Drivers,
Models, and Simulator Models, respectively, are located.  (For example, in bash
you could execute the command

$ export KIM_API_MODELS_DIR=/my-kim-stuff/models-i-am-developing:/my-kim-stuff/misc-models

to have the KIM API look for Models in /my-kim-stuff/models-i-am-developing
first and then look in /my-kim-stuff/misc-models.  (Similarly for Model Drivers
and Simulator Models.)  The environment-variable-collection may be populated
with Model Drivers, Models, and Simulator Models after the KIM API has been
built and installed.

C.2.4 THE CWD-COLLECTION

The CWD-collection is a collection of Model Drivers, Models, Simulator Models
that are available to a Simulator at run-time.  The collection is located in
the Simulator process's current working directory (CWD).  The CWD-collection
may be populated with Model Drivers, Models, and Simulator Models after the KIM
API has been built and installed.

C.3 HELPER UTILITIES

The KIM API package also includes a utility for managing the model drivers,
models, and simulator models contained in the various collections and for
managing the configuration file.  This utility is called
"kim-api-collections-management".  The KIM API package installs bash completion
scripts that are designed to work with the "bash-completion" package
(https://github.com/scop/bash-completion).  When "bash-completion" is installed
and activated on the system, tab-completions for the collections management
utility should be automatically loaded and available for use.

In addition, when the KIM API package is installed to a "Local (non-global)"
(see D below) directory, the package also installs the "kim-api-activate" and
"kim-api-deactivate" scripts.  The activate script adds the utilities to the
executable PATH, adds the KIM API library to the PKG_CONFIG_PATH so that the
pkg-config utility can find it, and loads bash tab-completion support for the
collections management utility.  The deactivate script removes what the
activate script added.


-------------------------------------------------------------------------------

D. KIM API INSTALLATION

D.1 Typical Build Scenario

Here, the typical KIM API build and install process is detailed and the
system-collection is populated with the example model drivers, models, and
simulator models, as well as a single Model and its associated Model Driver,
both from openkim.org.  Additionally, one of the example Simulators is copied
to the user's home directory and used to test the KIM API.  The KIM API package
uses the CMake build system.  See the CMake documentation
(https://cmake.org/cmake/help/v3.4/) for help with CMake settings.  For some
common CMake settings and KIM API specific settings, see D.2 below.

The commands given below are for the bash shell.

By default packages are installed to the Global prefix directory "/usr/local".
Here we assume that "/usr/local/bin" is included as part of the system's
standard PATH setting.

$ cd "${HOME}"
$ wget https://s3.openkim.org/kim-api/kim-api-X.Y.Z.txz  # replace X, Y, and Z with the current version numbers
$ tar Jxvf kim-api-X.Y.Z.txz
$ cd kim-api-X.Y.Z
$ mkdir build
$ cd build
$ cmake .. -DCMAKE_BUILD_TYPE=Release
$ make

If you want, build the documentation.

$ make docs

If you want, before installing the package, you can run the tests.

$ make test

Now, install the package (and docs, if built).

$ sudo make install
$ 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
$ cp -r ../examples/simulators/utility_forces_numer_deriv "${HOME}/"
$ cd "${HOME}"

If you want, you can now delete the source and build tree.  However, you may
also want to preserve the "install_manifest.txt" file which would be needed for
uninstalling the KIM API package (see D.4 below).

$ rm -r kim-api-X.Y.Z kim-api-X.Y.Z.txz # replace X, Y, and Z with the current version numbers

Now, we can build the simulator using the KIM API library that we have just
installed.

$ cd utility_forces_numer_deriv
$ mkdir build
$ cd build
$ cmake ..
$ make

Try it with one of the example models:
$ printf "ex_model_Ar_P_LJ" | ./utility_forces_numer_deriv

Next, we can try it with a model installed from https://openkim.org:
$ kim-api-collections-management install system --sudo EDIP_JustoBazantKaxiras_1998_Si__MO_958932894036_002
$ printf "EDIP_JustoBazantKaxiras_1998_Si__MO_958932894036_002" | ./utility_forces_numer_deriv

Congratulations, you have now successfully installed the KIM API.  If you would
like to learn more about the KIM API, read the documentation in the docs
directory (/usr/local/share/doc/kim-api).

D.2 CMAKE BUILD OPTIONS

The KIM API defines a number of specific build options which are detailed in
this section.  But first, some notes about a few important standard CMake
options.

D.2.1 COMPILER SELECTION

By default CMake will search for appropriate compilers available on your
system.  Generally, it selects reasonable choices.  However, if you wish to
force CMake to use specific compilers, you can do so with environment variables
set on the command line.  For example, suppose you have the latest GNU Compiler
Collection (GCC) version X installed with the compilers named 'gcc-X', 'g++-X',
and 'gfortran-X', for the C, C++, and Fortran compilers, respectively.  Then,
to force CMake to use these compilers, replace the command (from above)

$ cmake .. -DCMAKE_BUILD_TYPE=Release

with

$ CC=gcc-X CXX=g++-X FC=gfortran-X cmake .. -DCMAKE_BUILD_TYPE=Release

D.2.2 CMAKE_BUILD_TYPE

CMake defines the option CMAKE_BUILD_TYPE which can be set to "Debug",
"Release", "RelWithDebInfo", and "MinSizeRel".  (See the CMake documentation
for more details.)  By default CMAKE_BUILD_TYPE is empty.  In short, while
developing code or debugging, the value of "Debug" should be used.  When
building for production runs one of the other values should be used.

D.2.3 INSTALLATION PREFIX

By default CMake installs the KIM API package under the Global prefix
"/usr/local".  This is referred to as a "Global" (or system-wide) installation.
It is available to all users of the system.  (Other "Global" prefix values are
"/" and "/usr".)  However, such installations require root user permissions (as
implied by the use of the "sudo" command above).  If you do not have root user
permission and/or do not want to install the KIM API to the global location,
you can change where CMake installs the KIM API by replacing the command (from
above)

$ cmake .. -DCMAKE_BUILD_TYPE=Release

with

$ cmake .. -DCMAKE_INSTALL_PREFIX="/install/prefix/path" -DCMAKE_BUILD_TYPE=Release

where "/install/prefix/path" should be replaced with your desired prefix.  For
example, to install the KIM API in the "local" subdirectory of your home
directory, use "${HOME}/local".  When installed in such a directory, the user
may employ the "kim-api-activate" utility to setup the PATH and bash
completions.  For example:

$ source ${HOME}/local/bin/kim-api-activate

D.2.4 KIM API SPECIFIC BUILD OPTIONS

The KIM API defines two additional regular build options and additional
advanced options.

* KIM_API_LOG_MAXIMUM_LEVEL (="DEBUG" if CMAKE_BUILD_TYPE is "Debug", otherwise
  ="INFORMATION") This option takes one of the following six values "SILENT",
  "FATAL", "ERROR", "WARNING", "INFORMATION", "DEBUG".  This value controls, at
  compile-time, which type of log messages can be printed to the "kim.log"
  file.

* KIM_API_BUILD_EXAMPLES (=ON) When ON CMake will build the example models and
  simulators.  NOTE: this option may be removed/changed in future releases when
  the examples are incorporated into the documentation.

Additionally, the KIM API defines the following advanced build options.

* KIM_API_ENABLE_SANITIZE (=OFF) When ON this enables the AddressSanitizer
  library for detecting memory corruption bugs.

* KIM_API_ENABLE_COVERAGE (=OFF) When ON this enables gcov code coverage.

* KIM_API_PROJECT_NAME (="kim-api") This value controls the naming of many
  aspects of the package build.  Generally this should not be changed.  It can
  be used to build and install, on the same machine, two different copies
  (typically different versions) of the package.

* KIM_API_USER_CONFIGURATION_FILE (=".${PROJECT_NAME}/config") This value
  determines the default name of the KIM API user configuration file.  If the
  value corresponds to a relative path (does not start with "/"), then it is
  interpreted as relative to the user's home directory "${HOME}".

* KIM_API_SYSTEM_MODEL_DRIVERS_DIR
  (="${CMAKE_INSTALL_FULL_LIBDIR}/${PROJECT_NAME}/model-drivers") This value
  specifies a colon ':' separated list of the model drivers directory locations
  in the system collection.  If the value starts with a colon, cmake will
  update it by prepending the default value.

* KIM_API_SYSTEM_MODELS_DIR
  (="${CMAKE_INSTALL_FULL_LIBDIR}/${PROJECT_NAME}/models") This value specifies
  a colon ':' separated list of the models directory locations in the system
  collection.  If the value starts with a colon, cmake will update it by
  prepending the default value.

* KIM_API_SYSTEM_SIMULATOR_MODELS_DIR
  (="${CMAKE_INSTALL_FULL_LIBDIR}/${PROJECT_NAME}/simulator-models") This value
  specifies a colon ':' separated list of the simulator models directory
  locations in the system collection.  If the value starts with a colon, cmake
  will update it by prepending the default value.

* KIM_API_CMAKE_C_COMPILER (="${CMAKE_C_COMPILER}") This value is recorded and
  used after installation for compilation of items (models, model drivers,
  etc.) to ensure binary compatibility with the installed KIM API.

* KIM_API_CMAKE_CXX_COMPILER (="${CMAKE_CXX_COMPILER}") This value is recorded
  and used after installation for compilation of items (models, model drivers,
  etc.) to ensure binary compatibility with the installed KIM API.

* KIM_API_CMAKE_Fortran_COMPILER (="${CMAKE_Fortran_COMPILER}") This value is
  recorded and used after installation for compilation of items (models, model
  drivers, etc.) to ensure binary compatibility with the installed KIM API.

D.3 Installing multiple versions

On linux and macOS systems if you intend to install multiple versions of the
KIM API using the same installation prefix
("-DCMAKE_INSTALL_PREFIX=/install/prefix/path" argument to cmake) you must take
care that the installations do not overwrite each other.  If you intend to
install multiple versions using the same prefix you must use the
"-DKIM_API_PROJECT_NAME=project-name" argument (See D.2.4 above) to cmake and
use a unique value (any string without whitespace or control characters is
valid) for each installation.

Full support for the "-DKIM_API_PROJECT_NAME" argument, as described here, was
first available in v2.0.2.  For example, suppose the current version of the KIM
API were v3.2.1, and you want to also install KIM API v3.0.0, and v2.1.1.
Then, you would configure each version as follows:

 * v3.2.1

   $ cmake .. [additional args]  # use default ("kim-api") for current version.

 * v3.0.0

   $ cmake .. -DKIM_API_PROJECT_NAME=kim-api3.0 [additional args]

 * v2.1.1

   $ cmake .. -DKIM_API_PROJECT_NAME=kim-api2.1 [additional args]

D.4 Uninstall the KIM API

When the KIM API package is installed, CMake creates a file in the build tree
named "install_manifest.txt".  For the above commands this file would be
located at "${HOME}/kim-api-X.Y.Z/build/install_manifest.txt".  The manifest
file contains the absolute file name of every file installed as part of the KIM
API package.  The contents of the install_manifest.txt file can be used to
remove these files and, thus, uninstall the KIM API package.  Thus, the
install_manifest.txt file should be saved for later use, if necessary.

For example, the following commands could be used to uninstall the KIM API
package (assuming the "install_manifest.txt" file is located in your home
directory).

$ cd "${HOME}"
$ while read line || test -n "${line}"; do sudo rm -f "${line}"; done < install_manifest.txt

A more sophisticated set of commands could also remove any empty subdirectories
left behind by this process.

It may also be desirable to remove the user configuration file and user
collection directories.

$ rm -rf "${HOME}/.kim-api"


-------------------------------------------------------------------------------

E. ADDING MDs, MOs, and SMs TO THE COLLECTIONS


Here we describe how to add Models and/or Model Drivers to the
system-collection, user-collection, environment-variable-collection, and the
CWD-collection.

E.1 ADDING MDs, MOs, and SMs TO THE SYSTEM-COLLECTION

Once you have the KIM API installed, it is easy to add additional Models and/or
Model Drivers to the system-collection.

$ cd "${HOME}

$ kim-api-collections-management install system --sudo Morse_Shifted_Jelinek_1972_Ar__MO_831902330215_002

The kim-api-collections-management utility automatically installs the necessary
Model Driver.  You can see the items in the various collections by executing
the following command.

$ kim-api-collections-management list

Now we can test the newly installed Model.

$ cd "${HOME}/utility_forces_numer_deriv/build"  # we'll assume this is already built
$ printf "Morse_Shifted_Jelinek_1972_Ar__MO_831902330215_002" | ./utility_forces_numer_deriv

E.2 ADDING MDs, MOs, and SMs TO THE USER-COLLECTION

Adding MDs, MOs, and SMs to the user-collection is similar.

$ cd "${HOME}"

$ kim-api-collections-management install user LJ_Shifted_Bernardes_1958HighCutoff_Ar__MO_242741380554_003
$ kim-api-collections-management list
$ cd "${HOME}/utility_forces_numer_deriv/build"  # we'll assume this is already built
$ printf "LJ_Shifted_Bernardes_1958HighCutoff_Ar__MO_242741380554_003" | ./utility_forces_numer_deriv

E.3 ADDING MDs, MOs, and SMs TO THE ENVIRONMENT-VARIABLE-COLLECTION

Adding MDs, MOs, and SMs to the environment-variable-collection is similar.

$ cd "${HOME}"

$ mkdir -p "${HOME}/my-env-collection/model-drivers"
$ export KIM_API_MODEL_DRIVERS_DIR="${HOME}/my-env-collection/model-drivers"
$ mkdir -p "${HOME}/my-env-collection/models"
$ export KIM_API_MODELS_DIR="${HOME}/my-env-collection/models"
$ kim-api-collections-management install environment Morse_Shifted_GirifalcoWeizer_1959HighCutoff_Cu__MO_151002396060_002
$ kim-api-collections-management list
$ cd "${HOME}/utility_forces_numer_deriv/build"  # we'll assume this is already built
$ printf "Morse_Shifted_GirifalcoWeizer_1959HighCutoff_Cu__MO_151002396060_002" | ./utility_forces_numer_deriv

E.4 ADDING MDs, MOs, and SMs TO THE CWD-COLLECTION

Adding MDs, MOs, and SMs to the CWD-collection is, again, similar.

$ cd "${HOME}"

$ kim-api-collections-management install CWD Exp6_KongChakrabarty_1973_ArNe__MO_946046425752_002
$ kim-api-collections-management list
$ cd "${HOME}/utility_forces_numer_deriv/build"  # we'll assume this is already built
$ printf "Exp6_KongChakrabarty_1973_ArNe__MO_946046425752_002" | ./utility_forces_numer_deriv

E.5 Manually adding MDs, MOs, and SMs

If necessary a model driver, model, or simulator model may be manually built
and installed.  We'll assume the item's source code is in the current directory

$ mkdir build
$ cd build
$ cmake .. -DKIM_API_INSTALL_COLLECTION=SYSTEM
$ make
$ sudo make install

The KIM_API_INSTALL_COLLECTION variable can also take values USER and
ENVIRONMENT.

*******************************************************************************

SUPPORT

If you have problems or questions, send an email with your question and all
relevant information to

openkim@googlegroups.com

The members of the OpenKIM development team actively monitor this email list
and will do their best to help you with your question in a timely fashion.

*******************************************************************************
