#
# 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--2014, Regents of the University of Minnesota.
# All rights reserved.
#
# Contributors:
#    Ryan S. Elliott
#    Ellad B. Tadmor
#    Valeriu Smirichinski
#

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


============================= 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.  NOTE: shell commands provided in this file
are designed for use in the bash shell.

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

SYSTEM REQUIREMENTS

To install the KIM API package you need the following:

1. A Unix/Linux/Mac OSX/Cygwin 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: ar, printf, sed, ed, grep, find, cat, test, cp, touch,
   rm, rmdir, ln, install (needed for use in the build system).

5. wget and tar (needed for use with the `make add-<...>' build targets).

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

The KIM API package consists of a system-wide library and a small number of
associated helper executables.  The package is designed to be installed to the
standard system-wide library (/usr/local/lib), header (/usr/local/include), and
binary (/usr/local/bin) directories.  Or, if you do not have root access to
your system, to the standard directories (~/lib, ~/include, and ~/bin,
respectively) within your user account.  Of course, if you prefer to install
the KIM API elsewhere, there are settings described below that will allow you
to do so.  Or, you can simply use the KIM API "in place" from the source
directories.

The KIM API allows you to use Models that you develop or obtain from
https://openkim.org with any "KIM-Compliant" Simulator.  Depending on the value
of the configuration setting `KIM_LINK', described below, the set of accessible
Models is either (for `static-link' or `dynamic-link') defined and fixed at
build time, or (for `dynamic-load') may be changed at any time and even may be
different for each user account on the system.


QUICK START (default settings are appropriate for most Linux systems):

To install the KIM API to the standard location (/usr/local)

% cp Makefile.KIM_Config.example Makefile.KIM_Config
% printf "g/^KIM_DIR/d\\ni\nKIM_DIR = `pwd`\n.\nw\nq\n" | ed Makefile.KIM_Config
% make
% make install
% make install-set-default-to-vX  # replace X with the major version of this package

To install the KIM API to an alternative location (/path/to/alternate/location)

% cp Makefile.KIM_Config.example Makefile.KIM_Config
% printf "g/^KIM_DIR/d\\ni\nKIM_DIR = `pwd`\n.\nw\nq\n" | ed Makefile.KIM_Config
% prefix=/path/to/alternate/location
% printf "g/^#prefix/d\\ni\nprefix = ${prefix}\n.\nw\nq\n" | ed Makefile.KIM_Config
% make
% make install
% make install-set-default-to-vX  # replace X with the major version of this package


INSTRUCTIONS for building and installing this KIM API release:

0. If you have previously used the KIM API package (openkim-api versions 1.5.0
   or below), it is recommended that you remove all associated environment
   variables from your environment.  (These include, KIM_DIR, KIM_INTEL,
   KIM_SYSTEM32, KIM_DYNAMIC, KIM_API_DIR, KIM_TESTS_DIR,
   KIM_MODEL_DRIVERS_DIR, and KIM_MODELS_DIR.)  All settings are now specified
   in the Makefile.KIM_Config file.

1. Set up the Makefile.KIM_Config file

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

       % cd ${HOME}/kim-api-vX.X.X
       % cp Makefile.KIM_Config.example Makefile.KIM_Config

       The `%' symbol represents the bash sell prompt and should not be typed.

       (Above `vX.X.X' represents the current release 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 above, this would be

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

   (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',
       `dynamic-link', and `static-link'.

       KIM_LINK = dynamic-load

       `dynamic-load' is the preferred setting.  (Unless performance or other
       issues require it, you should use dynamic-load.)  `dynamic-link' is like
       `dynamic-load' but does not use the dl.h library.  This setting requires
       a more complicated build process, but may improve computation time in
       some instances.  `static-link' only works with ONE Model and AT MOST ONE
       Model Driver (in order to avoid the possibility of symbol clashes).
       This setting is designed for use in production runs on massively
       parallel computing systems where the use of dynamic libraries can have a
       significant negative impact on run times.

       * NOTE: When using the dynamic-link or static-link settings the entire
               KIM API must be recompiled when the list of Model Drivers and/or
               Models to be built changes.  This is not the case for the
               dynamic-load setting.

   (g) Set the value of KIM_BUILD_VERBOSITY, if a value other than the default
       (`quiet') is desired.  Possible values are `quite' 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) 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   =

       # override default linker options
       LDSHAREDFLAG =
       LINKSONAME =
       LDWHOLEARCHIVESTARTFLAG =
       LDWHOLEARCHIVEENDFLAG =


       * 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 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'

       * NOTE: For Cygwin systems add the following line `PICFLAG =' to avoid
               warnings about the -fPIC option.

   (i) 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
       package_name = # default is 'kim-api'
       prefix =       # default is '/usr/local'
       includedir =   # default is '$(prefix)/include'
       exec_prefix =  # default is '$(prefix)'
       libdir =       # default is '$(exec_prefix)/lib'
       bindir =       # default is '$(exec_prefix)/bin'


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

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

       * 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.

2. In the remainder of the documentation we will use the string ${KD} to
   represent the location of the KIM API source package (the value of the
   KIM_DIR variable discussed above).  If you wish to, type the below commands
   exactly (except for replacing the X.X.X as appropriate) as written to set
   the (bash) shell variable KD to the appropriate value:

   % KD=${HOME}/kim-api-vX.X.X

   We will assume you are using the following settings (with all other settings
   having their default values):

     KIM_LINK = dynamic-load
     prefix = $(HOME)/my-kim-files

   Finally, we will assume that you want to "add" the following OpenKIM Model
   Drivers and Models for "system-wide" use (see item 7 below):

     EAM_Dynamo__MD_120291908751_001
     EAM_Dynamo_Angelo_Moody_NiAlH__MO_418978237058_001

3. To build the package "in place", including the provided examples, and
   confirm that everything works as expeced, execute the following commands.

   First, change to the KIM API package directory:

   % cd ${KD}

   Second, "add" the OpenKIM Model Drivers and Models of interest:

   % make add-EAM_Dynamo__MD_120291908751_001
   % make add-EAM_Dynamo_Angelo_Moody_NiAlH__MO_418978237058_001

   Alternatively, you can just "add" the OpenKIM Model of interest and the
   associated Model Driver, if any, will also be added automatically:

   % make add-EAM_Dynamo_Angelo_Moody_NiAlH__MO_418978237058_001

   Finally, build the package and the provided examples:

   % make
   % make examples

   This builds the (1) KIM API library and its associated helper utilities, (2)
   the "added" Model Drivers and Models, and (3) the provided examples.  The
   targets defined by the top level KIM API Makefile include:

     `all'                        -- build the KIM API library and all "added"
                                     Model Drivers and Models; same as `make'
     `clean'                      -- delete appropriate .o, .mod, .a, .so and
                                     executable files from src/ directory and
                                     its subdirectories


     `ls-all'                     -- list all "added" Model Drivers and Models
     `ls-model-drivers'           -- list all "added" Model Drivers
     `ls-models'                  -- list all "added" Models

     `add-OpenKIM'                -- "add" all OpenKIM Model Drivers and Models
     `add-<Extended KIM ID>'      -- "add" <Extended KIM ID> from OpenKIM
                                     including the associated Model Driver, if
                                     appropriate
     `add-examples'               -- "add" example Model Drivers and Models

     `rm-all'                     -- "rm" all "added" Model Drivers and Models
     `rm-all-model-drivers'       -- "rm" all "added" Model Drivers
     `rm-all-models'              -- "rm" all "added" Models
     `rm-<Extended KIM ID>'       -- "rm" the "added" <Extended KIM ID> item
     `rm-examples'                -- "rm" the "added" example Drivers and Models


     `install'                    -- install KIM API library, associated
                                     executable utilities, and "added" Model
                                     Drviers and Models to system-wide location
                                     as described in item 7 below.
     `install-set-default-to-vX'  -- create generic
                                     ${includedir}/${package_name} and
                                     ${libdir}/${package_name} symlinks to the
                                     corresponding ${package_name}-vX versions.
                                     This effectively sets the "default"
                                     library available for users on the system.
     `uninstall'                  -- delete files installed by `make install'
     `uninstall-set-default'      -- remove the generic
                                     ${includedir}/${package_name} and
                                     ${libdir}/${package_name} symlinks.


     `examples'                   -- build all provided examples
     `examples-all'               -- same as `make examples'
     `examples-clean'             -- delete appropriate .o, .mod, .a, .so and
                                     executable files from examples/ directory
                                     and its subdirectories


4. Verify that the build was successful by running an OpenKIM Test "in place".

   The provided example OpenKIM Tests read in the name of a Model (or Models)
   which they use to perform their calculations.  For most Tests the name of
   the Model can be piped in using an `printf' command.  For example, the
   following Fortran 2003 Test reads in one Model name:

   % cd ${KD}/examples/openkim_tests/ex_test_Ar_free_cluster_CLUSTER_F03
   % printf "ex_model_Ar_P_MLJ_CLUSTER_C" | ./ex_test_Ar_free_cluster_CLUSTER_F03

   (See the README files in the openkim_tests/* directories for an explanation
   of what the Tests do.)

   * NOTE: Executing the example Simulators or OpenKIM Tests, as described
           above, uses the KIM API "in place".  That is, the executable looks
           for the KIM API library in the directory ${KD}/src.  If you only
           need to use the KIM API briefly, this is a perfectly acceptable way
           to use the KIM API. In fact, you can have other Simulators, such as
           LAMMPS or IMD, link to this "in place" version of the KIM API by
           appropriately configuring these packages.  However, if you expect to
           use the KIM API on a routine basis, it is recommended that you
           install the KIM API to a "system-wide" location.  See item 7 below
           for more details on the installation process.

5. When compiled with KIM_LINK=dynamic-load, the KIM API will look for Model
   Driver and Model directories in three different locations: the current
   working directory (CWD), the directory listed in the user configuration
   file, and the system-wide Model Drivers and Models directories.  For Model
   Drivers the directories, listed in the order they are searched, are:

     (a) `.'                                            ("CWD Model Drivers")
     (b) as listed in the user configuration file       ("User Model Drivers")
     (c) `${libloc}/model_drivers'                      ("System Model Drivers")

   For Models the directories, listed in the order they are searched, are:

     (a) `.'                                            ("CWD Models")
     (b) as listed in the user configuration file       ("User Models")
     (c) `${libloc}/models'                             ("System Models")

   The user configuration file is for specifying the "User Model Drivers" and
   "User Models" directories to be searched.  Create this file in the directory
   `${configloc}/.${package_name}/config-vX' where X is replaced by the major
   version number for this release of the KIM API package (as defined in the
   file Makefile.Version).  For "in place" use of the KIM API, libloc=${KD}/src
   and configloc=${KD}.  For "installed" use of the KIM API,
   libloc=$(libdir)/$(full_package_name) and configloc=$(HOME).  By default,
   package_name=kim-api, full_package_name=kim-api-vX, and
   libdir=/usr/local/lib.

   The file `${configloc}/.${package_name}/config-vX' has a strict format.  It
   must contain exactly two lines.  These must be of the form:

     model_drivers_dir = XXX
     models_dir = YYY

   where XXX and YYY are replaced by paths (beginning with `/' or `~/' only)
   which indicate where you will store your Model Drivers and Models,
   respectively.

   * NOTE: executing `make examples' automatically creates the file
           `${KD}/.kim-api/config-vX' with the following content:

             model_drivers_dir = ${KD}/examples/model_drivers
             models_dir = ${KD}/examples/models

           with ${KD} fully expanded to an absolute path.  This ensures that
           the provided example Model Drivers and Models will be found by the
           KIM API library when it is used "in place", as was done above in
           item 4.  The contents of this user configuration file may be changed
           as you wish.

6. Each example Model Driver, Model, Simulator, and OpenKIM Test has its own
   Makefile for building.  If changes are made to the example codes, simply run
   `make' from the associated directory to update the build for that item.

7. Install the KIM API to the system-wide directories.  (Recall that if you are
   using the KIM_LINK=dynamic-link or KIM_LINK=static-link settings you must
   rebuild and install the entire KIM API package in order to make changes
   (additions, removals, modification) to the set of system-wide installed
   Model Drivers and Models.  Conversely, if you are using the
   KIM_LINK=dynmaic-load setting, then you can make changes to the system-wide
   installed Model Drivers and Models at any time.)

   % cd ${KD}
   % make install

   The compiled versions of the KIM API library, associated binary utilities,
   Model Drivers, and Models will be copied to
   `$(libdir)/$(full_package_name)'.  The default value for libdir is
   `$(exec_prefix)/lib', the default value for exec_prefix is `$(prefix)', and
   the default value for prefix is `/usr/local'.  Thus, the default value of
   libdir is `/usr/local/lib'.  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.

   If you want these files to be the default version of the KIM API package on
   your system (i.e., accessible via ${includedir}/${package_name} and
   ${libdir}/lib${package_name}.so), then do:

   % make install-set-default-to-vX

   Once the KIM API package has been installed, the original source directory
   (${KD}) may be deleted.  However, first we will make a copy, to our prefix
   directory (${HOME}/my-kim-files), of a couple of files that will be used
   later, in the next step.

   % prefix=${HOME}/my-kim-files
   % cp ${KD}/examples/openkim_tests/vc_forces_numer_deriv/vc_forces_numer_deriv.F03 ${prefix}/
   % cp ${KD}/examples/openkim_tests/vc_forces_numer_deriv/Makefile ${prefix}/

   Now we can delete the KIM API source package:

   % cd ${HOME}
   % rm -r ${KD}

8. If the KIM API has been installed using KIM_LINK=dynamic-load and the
   original source directory has been deleted, it is still possible to compile
   Model Drivers and Models.  These can be placed in the current working
   directory (CWD), or in the directory listed in the user configuration file,
   or installed in the system-wide Model Drivers and Models directories.  To
   create a new Model Driver of Model and install it in the appropriate
   system-wide directory or in the directory listed in the user configuration
   file, follow these steps:

   (a) If you don't want to set up a user configuration file, skip to item (b).
       Otherwise, create these files now (here we will use
       `${prefix}/my-kim-items' as an example):

       % mkdir ${prefix}/my-kim-items
       % package_name=kim-api
       % mkdir ${HOME}/.${package_name}
       % cd ${HOME}/.${package_name}
       % printf "model_drivers_dir = ~/my-kim-files/my-kim-items\n" > config-vX
       % printf "models_dir = ~/my-kim-files/my-kim-items\n" >> config-vX

       Do not forget to replace `X' with the major version number of this
       package.  Although here we use the same directory for Model Drivers and
       Models, this is not necessary and separate directories may be specified.
       Now skip to item (c).

   (b) For those who want to work in the current directory (CWD) and/or install
       additional Model Drivers and Models system-wide, we'll create a
       temporary directory in which to work (here we use
       `${prefix}/my-kim-items' as an example):

       % mkdir ${prefix}/my-kim-items
       % package_name=kim-api # for use in (d) below

   (c) Next, for convenience, we'll create an environment variable pointing to
       our working directory:

       % WD=${prefix}/my-kim-items

   (d) Create a Makefile.KIM_Config in the ${WD} directory (we will use the
       provided "build-config" utility to do this):

       % PATH=${PATH}:${prefix}/bin  # Make sure that ${prefix}/bin is on the path
       % libdir=${prefix}/lib
       % cd ${WD}
       % ${package_name}-build-config --makefile-kim-config > ${WD}/Makefile.KIM_Config

       The ${pakcage-name}-build-config (kim-api-build-config, by default)
       utility outputs various strings that can be used to help build
       Simulators and, as used here, to create Makefile.KIM_Config files.

   (e) We will work with the case of a Model Driver and an associated
       Parameterized Model such as those you can download from
       https://openkim.org.  For example, execute the following commands:

       % md=Pair_Morse_Shifted__MD_552566534109_001
       % wget --content-disposition "https://kim-items.openkim.org/archive?kimid=${md}&compression=gz"
       % tar zxvf ${md}.tgz
       % rm ${md}.tgz
       % mo=Pair_Morse_Shifted_Jelinek_Ar__MO_831902330215_001
       % wget --content-disposition "https://kim-items.openkim.org/archive?kimid=${mo}&compression=gz"
       % tar zxvf ${mo}.tgz
       % rm ${mo}.tgz

   (f) Compile the Model Driver and Model:

       % cd ${WD}/${md}
       % make
       % cd ${WD}/${mo}
       % make

       You can now use the Model from the current working directory (${WD}).
       For example, you could copy, compile and run the example Verification
       Check `vc_forces_numer_deriv':

       % cd ${WD}
       % cp ${prefix}/vc_forces_numer_deriv.F03 ${WD}
       % cp ${prefix}/Makefile ${WD}
       % make
       % printf "${mo}" | ./vc_forces_numer_deriv

       If you have setup the user configuration file, you have a new User Model
       installed in the user specified directory and you can skip the rest of
       the below steps.  In order to use your new Model you can, for example,
       compile and run the example Verification Check `vc_forces_numer_deriv'
       in whatever directory you like:

       % EXD=${prefix}/my-executable
       % mkdir ${EXD}
       % cd ${EXD}
       % cp ${prefix}/vc_forces_numer_deriv.F03 ${EXD}
       % cp ${prefix}/Makefile ${EXD}
       % make
       % printf "${mo}" | ./vc_forces_numer_deriv

   (g) If you want to install this Model Driver and Model in the appropriate
       system-wide directories, then execute the following commands in order to
       do so:

       % cd ${WD}/${md}
       % make install
       % cd ${WD}
       % rm -rf ${WD}/${md}
       % cd ${WD}/${mo}
       % make install

       * NOTE: for Parameterized Models, such as ${mo}, you must install and
               delete the associated Model Driver before installing the Model,
               as we have done above.

       You have now installed the Model Driver and Model to the system-wide
       directories and you can delete the remaining source directories:

       % cd ${WD}
       % rm -rf ${WD}/${mo}

       Finally, you can run the executable again:

       % cd ${EXD}
       % printf "${mo}" | ./vc_forces_numer_deriv


Once the compilation and installation is successfully completed, read the
README file in the docs directory for a step-by-step guide to learning more
about the KIM API.

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

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.

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