#
# 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--2018, 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.git repository.
#


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

This file contains instructions for installing the KIM API package.  If you are
new to KIM and the KIM API (application programming interface) start by reading
the README file in this directory.


TABLE OF CONTENTS

A. System requirements

B. Quick start

C. Package layout and operation overview
   C.1 Build types
       C.1.1 Installed-build
   C.2 Model and Model Driver 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

D. KIM API Installation scenario recipes
   D.1 Installed-build
       D.1.1 Installed-(standard)-build
       D.1.2 Installed-(nonstandard)-build

E. Adding Models and/or Model Drivers to the collections
   E.1 Adding Models and/or Model Drivers to the system-collection
   E.2 Adding Models and/or Model Drivers to the user-collection
   E.3 Adding Models and/or Model Drivers to the environment-variable-collection
   E.4 Adding Models and/or Model Drivers to the CWD-collection

F. Advanced documentation for KIM API build and install process
   F.1 The Makefile.KIM_Config file
   F.2 Make targets defined by the top level KIM API Makefile
   F.3 Advanced details of the installation process

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

A. SYSTEM REQUIREMENTS


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

1. A Unix/Linux/osX system.

2. GNU make (3.81 or later).

3. GNU compilers (gcc, g++, gfortran) version 4.2.x or higher or the
   corresponding Intel compilers, version 11.1 or higher.  NOTE: gfortran 4.6.x
   is known to have subtle bugs, and SHOULD NOT BE USED with the KIM API
   software package.

4. Standard utilities: xxd, ar, printf, sed, grep, find, cat, test, cp, touch,
   rm, rmdir, ln, chmod, install (needed for use in the build system).

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

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

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


Jump directly to sections D.1 or D.2.

If you have any problems with the commands found there, please read the rest of
this file.  If, however, you have successfully installed the KIM API and you
would like to learn more, read the documentation found in the docs directory.

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

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
that can seamlessly interface with implementations of interatomic models,
regardless of the programming language in which the codes are written.

C.1. BUILD TYPES

The KIM API package consists of a main library and a small number of associated
helper utilities.

C.1.1 INSTALLED-BUILD

This build type comes in two flavors: installed-(standard)-build and
installed-(nonstandard)-build.  These two flavors are identical except for
where the KIM API is installed within the system's file system.

The KIM API package is designed to be installed to a standard system-wide
directory ("/usr/local", by default, but "/" or "/usr" are also standard
locations) with its libraries placed in /usr/local/lib, header files placed
in /usr/local/include, and binaries placed in /usr/local/bin.  If you do
not have root access to your system, the KIM API may be installed to the
standard directories (${HOME}/local/lib, ${HOME}/local/include, and
${HOME}/local/bin, respectively) within your user account home directory.  Of
course, if you prefer to install the KIM API elsewhere, there are settings that
will allow you to do so.  Once the KIM API is installed, the package source
code directories are no longer needed and should be removed in order to keep
your system tidy.

With the KIM API successfully installed on your system, it is possible to build
KIM-Compliant Simulators (such as molecular dynamics programs) against the
KIM API library.  Each such Simulator has its own build instructions that should
be followed in order to build it with KIM API support enabled.

C.2 MODEL AND MODEL DRIVER COLLECTIONS

The KIM API supports four "collections" of Models and Model Drivers.  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 or Model Driver, it looks for
the Model 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 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 Models and Model Drivers that are
available to all Simulators that use the KIM API library.  This collection is
located in the same subdirectory as the KIM API main library.

Models and Model Drivers may be built and installed to the system-collection at
anytime after an installed-build of the KIM API has been completed.

C.2.2 THE USER-COLLECTION

The user-collection is a collection of Models and Model Drivers that are
available only to the system 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 Models and Model Drivers after an installed-build of the KIM API has been
completed.

The configuration file is named "config-vX" and, by default, is located in the
directory "${HOME}/.kim-api/".  (See item F.1.i, below for build-time settings
controlling this directory name.)  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/vX_model_drivers/" and
"${HOME}/.kim-api/vX_models/".  If the "KIM_API_VX_USER_CONFIG_FILE" environment
variable is set, its value (interpreted as an absolute file name) will
supersede the default location and name of the configuration file.

C.2.3 THE ENVIRONMENT-VARIABLE-COLLECTION

The environment-variable-collection is a collection of Models and Model Drivers
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_VX_MODELS_DIR" and
"KIM_API__VX_MODEL_DRIVERS_DIR".  These variables should contain colon ':'
separated lists of absolute directory names where the collection Models and
Model Drivers, respectively, are located.  (For example, in bash you could
execute the command

$ export KIM_API_VX_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.)  The environment-variable-collection may be populated with Models and
Model Drivers after an installed-build of the KIM API has been completed.


C.2.4 THE CWD-COLLECTION

The CWD-collection is a collection of Models and Model Drivers 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 Models and Model Drivers after an installed-build of the KIM API
has been completed.

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

D. KIM API INSTALLATION SCENARIO RECIPES


D.1 INSTALLED-BUILD

In this scenario the KIM API is built and installed and the system-collection
is populated with 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 installed-build.  If you need
special settings, see `./configure --help` and section H.1 for details about
the KIM API build settings.  The commands given below are for the bash shell.

We'll detail the two flavors: installed-(standard)-build and
installed-(nonstandard)-build.

D.1.1 INSTALLED-(STANDARD)-BUILD

To create an installed-(standard)-build and install to the default directory
"/usr/local" do the below.  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-vX.Y.Z.txz  # replace X.Y.Z with the current version number
$ tar Jxvf kim-api-vX.Y.Z.txz
$ cd kim-api-vX.Y.Z
$ ./configure
$ make
$ 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/openkim_tests/utility_forces_numer_deriv "${HOME}/"
$ cd "${HOME}"
$ rm -r kim-api-vX.Y.Z  kim-api-vX.Y.Z.txz # replace X.Y.Z with the current version number
$ kim-api-vX-collections-management install system --sudo EDIP_BOP_Bazant_Kaxiras_Si__MO_958932894036_001
$ cd utility_forces_numer_deriv
$ make
$ printf "EDIP_BOP_Bazant_Kaxiras_Si__MO_958932894036_001" | ./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.

D.1.2 INSTALLED-(NONSTANDARD)-BUILD

To create an installed-(nonstandard)-build and install to the user's home
directory "${HOME}/local" do the below.

$ cd "${HOME}"
$ wget https://s3.openkim.org/kim-api/kim-api-vX.Y.Z.txz  # replace X.Y.Z with the current version number
$ tar Jxvf kim-api-vX.Y.Z.txz
$ cd kim-api-vX.Y.Z
$ ./configure --prefix=${HOME}/local
$ make
$ make install
$ cp -r ./examples/openkim_tests/utility_forces_numer_deriv "${HOME}/"
$ cd "${HOME}"
$ rm -r kim-api-vX.Y.Z kim-api-vX.Y.Z.txz  # replace X.Y.Z with the current version number
$ source "${HOME}/local/bin/kim-api-vX-activate"  # add KIM API to the shell's ${PATH} and load bash tab-completions
$ kim-api-vX-collections-management install system EDIP_BOP_Belko_Gusakov_Dorozhkin_Ge__MO_129433059219_000
$ cd utility_forces_numer_deriv
$ make
$ printf "EDIP_BOP_Belko_Gusakov_Dorozhkin_Ge__MO_129433059219_000" | ./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.

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

E. ADDING MODELS AND/OR MODEL DRIVERS 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 MODELS AND/OR MODEL DRIVERS TO THE SYSTEM-COLLECTION

Once you have an installed-build, it is easy to add additional Models and/or
Model Drivers to the system-collection.  We'll assume an
installed-(standard)-build.

$ kim-api-vX-collections-management install system --sudo Pair_Morse_Shifted_Jelinek_Ar__MO_831902330215_001

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

$ cd "${HOME}"
$ kim-api-vX-collections-management list

Now we can test the newly installed Model.

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

E.2 ADDING MODELS AND/OR MODEL DRIVERS TO THE USER-COLLECTION

Adding Models and/or Model Drivers to the user-collection is similar.

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

E.3 ADDING MODELS AND/OR MODEL DRIVERS TO THE ENVIRONMENT-VARIABLE-COLLECTION

Adding Models and/or Model Drivers to the environment-variable-collection is
similar.

$ mkdir -p "${HOME}/my-env-collection/model_drivers"
$ export KIM_API_VX_MODEL_DRIVERS_DIR="${HOME}/my-env-collection/model_drivers"
$ mkdir -p "${HOME}/my-env-collection/models"
$ export KIM_API_VX_MODELS_DIR="${HOME}/my-env-collection/models"
$ kim-api-vX-collections-management install environment Pair_Morse_Shifted_GirifalcoWeizer_HighCutoff_Cu__MO_151002396060_001
$ kim-api-vX-collections-management list
$ cd "${HOME}/utility_forces_numer_deriv"  # we'll assume this is already built
$ printf "Pair_Morse_Shifted_GirifalcoWeizer_HighCutoff_Cu__MO_151002396060_001" | ./utility_forces_numer_deriv

Alternatively, you can just download and build the items.  Here, we'll
illustrate the process with an example.

$ mkdir -p "${HOME}/my-env-collection/model_drivers"
$ export KIM_API_VX_MODEL_DRIVERS_DIR="${HOME}/my-env-collection/model_drivers"
$ cd "${KIM_API_VX_MODEL_DRIVERS_DIR}"
$ md=Pair_Morse_Shifted__MD_552566534109_001
$ wget --content-disposition "https://openkim.org/download/${md}.txz"
$ tar Jxvf "${md}.txz"
$ cd "${md}"
$ make
$ cd ../
$ rm "${md}.txz"

$ mkdir -p "${HOME}/my-env-collection/models"
$ export KIM_API_VX_MODELS_DIR="${HOME}/my-env-collection/models"
$ cd "${KIM_API_VX_MODELS_DIR}"
$ mo=Pair_Morse_Shifted_GirifalcoWeizer_HighCutoff_Cu__MO_151002396060_001
$ wget --content-disposition "https://openkim.org/download/${mo}.txz"
$ tar Jxvf "${mo}.txz"
$ cd "${mo}"
$ make
$ cd ../
$ rm "${mo}.txz"

We can check to see that these are recognized by the KIM API.

$ cd "${HOME}"
$ kim-api-vX-collections-management list

Now we can test the newly available Model.

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

E.4 ADDING MODELS AND/OR MODEL DRIVERS TO THE CWD-COLLECTION

Adding Models and/or Model Drivers to the CWD-collection is, again, similar.

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

Alternatively, you can just download and build the items.  Here, we'll
illustrate the process with an example.

$ cd "${HOME}/utility_forces_numer_deriv"  # we'll assume this is already built
$ mo=Pair_Exp6_Hogervorst_Mixing_Kong_Chakrabarty_ArNe__MO_946046425752_001
$ wget --content-disposition "https://openkim.org/download/${mo}.txz"
$ tar Jxvf "${mo}.txz"
$ cd "${mo}"
$ make
$ cd ../
$ rm "${mo}.txz"

We can check to see that this model is recognized by the KIM API.

$ kim-api-vX-collections-management list

Now we can test the newly available Model.

$ printf "Pair_Exp6_Hogervorst_Mixing_Kong_Chakrabarty_ArNe__MO_946046425752_001" | ./utility_forces_numer_deriv

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

F. ADVANCED DOCUMENTATION FOR KIM API BUILD AND INSTALL PROCESS


F.1. THE Makefile.KIM_Config FILE

Here we describe the process of creating the configuration settings for the KIM
API build, which are contained in the Makefile.KIM_Config file.  This is
usually done by the `configure' script.  However, it may also be done by hand
if necessary.

(a) Copy the file `Makefile.KIM_Config.example' to `Makefile.KIM_Config'.
    For example, if you untarred the `kim-api-vX.Y.Z.txz' tarball in your
    home directory, you would do:

    $ cd ${HOME}/kim-api-vX.Y.Z
    $ cp Makefile.KIM_Config.example Makefile.KIM_Config

    (Above `vX.Y.Z' represents the current version number.)

(b) Edit the file Makefile.KIM_Config and set the appropriate value for the
    KIM_DIR variable.  This must expand to an absolute path.  Using the same
    assumptions as in (a), this would be

    KIM_DIR = $(HOME)/kim-api-vX.Y.Z

(c) Set the value of KIM_COMPILERSUITE.
    Possible values are `GCC' and `INTEL'.

    KIM_COMPILERSUITE = GCC

(d) Set the value of KIM_SYSTEMLINKER.
    Possible values are `linux', `freebsd', and `darwin'.

    KIM_SYSTEMLINKER = linux

(e) Set the value of KIM_SYSTEMARCH.
    Possible values are `32bit' and `64bit'.

    KIM_SYSTEMARCH = 64bit

(f) Set the value of KIM_LINK.
    Possible values are `dynamic-load'.

    KIM_LINK = dynamic-load

(g) Set the value of KIM_BUILD_VERBOSITY, if a value other than the default
    (`quiet') is desired.  Possible values are `quiet' and `full'.

    KIM_BUILD_VERBOSITY = quiet

    * NOTE: Alternatively you can override this variable's setting from the
            command line as you invoke make:

      $ make KIM_BUILD_VERBOSITY=full

(h) Set the value of KIM_LOG_MAXIMUM_LEVEL, if a value other than the default
    (`KIM_LOG_VERBOSITY_ERROR_') is desired.
    Possible values are `KIM_LOG_VERBOSITY_SILENT_',
    `KIM_LOG_VERBOSITY_FATAL_', `KIM_LOG_VERBOSITY_ERROR_',
    `KIM_LOG_VERBOSITY_WARNING_', `KIM_LOG_VERBOSITY_INFORMATION_',
    `KIM_LOG_VERBOSITY_DEBUG_'.

    KIM_LOG_MAXIMUM_LEVEL = KIM_LOG_VERBOSITY_DEBUG_

(i) Override default compiler options and other variables, if necessary, by
    adding the desired variable name (after the "# override default compiler
    options and other variables here" line) and filling in appropriate
    values.


    # override default compiler options and other variables here

    # override default compiler executable names and settings
    CC =
    CXX =
    FC =
    LD =

    # override default compiler option flag lists
    FFLAGS   =
    CFLAGS   =
    CXXFLAGS =
    LDFLAGS  =
    LDLIBS   =


    * NOTE: GCC 4.4 requires that LDLIBS be set as
            `LDLIBS = -lgfortran -lgfortranstart' or possibly
            `LD = $(FC)' and `LDLIBS = -lstdc++'.

    * NOTE: As of 2014-01-20, gfortran on Darwin OS (Mac OSX) has a bug
            associated with the use of iso_c_binding Fortran/C
            interoperability features which are now standard in KIM API.
            (See http://gcc.gnu.org/bugzilla/show_bug.cgi?id=59888 for
            details.)  We have reported this bug and are awaiting its fix.
            In the meantime, the following workaround has been identified:

            (1) You must have a "multi-library" version of gfortran
                installed on your mac due the need (see (2) below) to
                build for a 32bit architecture.  This means that GCC must
                have been configured with the "--enable-multilib" flag.  To
                check your version execute `gfortran -v' and look for the
                string "--enable-multilib".  In order to install a multilib
                version of gfortran on your mac you can use a package
                manager such as Homebrew, Mac Ports, or fink.  Follow the
                instructions for installing the package manager of your
                choice.  Then execute the command to install gfortran.

                For Homebrew the command is:
                  $ brew install gcc

                For Mac Ports the command is:
                  $ sudo port install gcc48 +universal
                  $ sudo port select --set gcc mp-gcc48
                  (Note, this may require that you build the package from
                   source in order to get the correct version.)

            (2) You must build the KIM API and associated Model Drivers,
                Models, and examples using the `KIM_SYSTEMARCH = 32bit'
                setting.

            (3) If appropriate, make sure the build system uses the brew
                installed compilers
                  `CC = gcc-4.8'
                  `CXX = g++-4.8'

            (4) You need to have the following line in this section of the
                Makefile.KIM_Config file in order to avoid harmless compiler
                errors:
                  `LDFLAGS += -read_only_relocs suppress'

(j) Override default name options, if necessary, by adding the desired variable
    name (after the "# override default name options" line) and filling in
    appropriate values.

    # override default name options
    package_name =               # default is 'kim-api'
    user_config_file_dir_name =  # default is '.$(package_name)'


    * NOTE: The package_name variable is used as part of the installation
            directory name and the KIM API library file name.

    * NOTE: The KIM API library will look for the user-collection configuration
            file in the directory '${HOME}/${user_config_file_dir_name}'

(k) Override default install options, if necessary, by adding the desired
    variable name (after the "# override default install options" line) and
    filling in appropriate values.

    # override default install options
    prefix =       # default is '/usr/local'
    exec_prefix =  # default is '$(prefix)'
    bindir =       # default is '$(exec_prefix)/bin'
    libexecdir =   # default is '$(exec_prefix)/libexec'
    sysconfdir =   # default is '$(prefix)/etc'
    libdir =       # default is '$(exec_prefix)/lib'
    includedir =   # default is '$(prefix)/include'


    * NOTE: See item F.3 below for more details on the installation process.

    * NOTE: See the GNU Coding Standards, Section 7.2 for more details on
            the meaning of the remaining standard variables.

    * NOTE: Staged installs are supported via the DESTDIR variable.  See
            Section 7.2.4 of the GNU Coding Standards.

F.2 MAKE TARGETS DEFINED BY THE TOP LEVEL KIM API Makefile

The targets defined by the top level KIM API Makefile include:

TARGETS FOR BUILDING AND CLEANING THE KIM API PACKAGE
`help'                       -- print this list of targets
`all'                        -- build the KIM API library; same as `make'
`clean'                      -- delete appropriate .o, .mod, .a, .so and
                                executable files.

TARGETS FOR INSTALLING THE KIM API PACKAGE
`install'                    -- install KIM API library, associated
                                executable utilities.

TARGETS FOR UNINSTALLING THE KIM API PACKAGE
`uninstall'                  -- delete files installed by `make install'


F.3 ADVANCED DETAILS OF THE INSTALLATION PROCESS

Upon `make install', the compiled versions of the KIM API library, associated
and binary utilities will be copied to `$(libdir)/$(full_package_name)/'.  The
bindir, libexecdir, includedir, and sysconfdir directories are also populated.
The default values for libdir, bindir, libexec, includedir, and sysconfdir are
`$(exec_prefix)/lib', `$(exec_prefix)/bin', `$(exec_prefix)/libexec',
`$(prefix)/include', and `$(prefix)/etc', respectively.  The default value for
exec_prefix is `$(prefix)', and the default value for prefix is `/usr/local'.
Thus, the default values of libdir, bindir, libexec, includedir, and sysconfdir
are `/usr/local/lib', `/usr/local/bin', `/usr/local/libexec',
`/usr/local/include', and `/usr/local/etc', respectively.  The value of
full_package_name is `$(package_name)-v$(VERSION_MAJOR)'.  Additionally the
supporting header and `.mod' files will be copied to
`$(libdir)/$(full_package_name)/include' to support subsequent compilation
against the installed KIM API package.

See the Makefiles in the various include and src directories for more details
of the install process.

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

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.

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