Permalink
88f264e Jun 26, 2018
2 contributors

Users who have contributed to this file

@ellio167 @tadmor
610 lines (446 sloc) 24.4 KB
#
# 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 README file in the docs directory for a
step-by-step guide to learning more about the KIM API.
-------------------------------------------------------------------------------
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_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_MODELS_DIR" and
"KIM_API_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_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 # 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 README file in the docs
directory for a step-by-step guide.
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 README file in the docs
directory for a step-by-step guide.
-------------------------------------------------------------------------------
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_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-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_MODEL_DRIVERS_DIR="${HOME}/my-env-collection/model_drivers"
$ cd "${KIM_API_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_MODELS_DIR="${HOME}/my-env-collection/models"
$ cd "${KIM_API_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) 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'
* NOTE: For Cygwin systems add the following line `PICFLAG =' to avoid
warnings about the -fPIC option.
(i) 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}'
(j) 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.
*******************************************************************************