Installation
Please see the file chemsh/src/config/INSTALL for installation
instructions. The following section is taken from this file.
1. Introduction
===============
The following instructions describe the steps required to install
ChemShell 3.7.
The instructions assume ChemShell will be built on a 64-bit Linux platform.
It should be possible in principle to install ChemShell on other
UNIX or UNIX-like platforms (e.g. Mac, cygwin), but we do not verify this.
It is useful to appreciate the directory structure, as follows
[root dir]
|
---------------------------------------------------------------......
| | | | | | | |
Makefile src/ bin/ lib/ scripts/ examples/ doc/ tcl/
|
----------.....
| |
chemsh mndocore
In these instructions [root dir] will be used to denote the root (top)
directory of the tree (usually called chemsh) in the following notes.
When unpacked, the distribution file will write a set of files
and directories, including those listed above, into the current
working directory.
2. Before Installation
======================
2.1 Tcl
-------
ChemShell is compatible with Tcl 8.4/8.5/8.6, with 8.5 the current
default. Although it is sometimes possible to use a system Tcl, we
strongly recommend you build it from source, as follows:
Assuming the Tcl code is to be built in the user directory /home/username/tcl
% cd /home/username/tcl
% gunzip tcl8.5.11-src.tar.gz
% tar xvf tcl8.5.11-src.tar
% cd tcl8.5.11/unix
% ./configure --prefix=/home/username/tcl/tcl8.5.11
% make
% make install
You can find a copy of the Tcl 8.5 source code on the Tcl website:
http://www.tcl.tk/software/tcltk/download.html
or from our FTP server at ftp://ftp.dl.ac.uk/qcg/ChemShell/tcl8.5.11-src.tar.gz
Certain platforms may not support either Tcl 8.5 or 8.6 in which case
Tcl 8.4 can be obtained from:
ftp://ftp.dl.ac.uk/qcg/ChemShell/tcl8.4.19-src.tar.gz
Please see note 3.1 below if you are compiling with either 8.4 or 8.6.
2.2 Direct linking of external codes
------------------------------------
The default method of running external codes from ChemShell is
by calling them as standalone executables, just as they would be
called from the command line. In this case, no special preparations
are required before installing ChemShell.
Note also that it is not necessary to compile ChemShell in
parallel in order to run standalone external codes in parallel
(in fact, the preferred strategy in this case is often to build
ChemShell in serial, as launching one program in parallel from
another running in parallel may not be possible depending on
the platform you are running on).
Alternatively, some external codes can be built as libraries
and linked directly into ChemShell to form a single executable.
This has some advantages particularly for parallel execution,
and enables the task-farming parallelisation methods described
in the manual.
The following sections give guidance for compiling codes which can be
directly linked. As of ChemShell 3.7 these are GAMESS-UK, NWChem,
Dalton, LSDalton, FHI-aims and GULP.
NB: In general no more than one QM code should be linked into a
given ChemShell build to avoid namespace collision issues.
-- GAMESS-UK library --
To build the GAMESS-UK code as a library, add the "chemshell"
keyword to the list of options selected when configuring GAMESS-UK.
You should also add the "qmmm" keyword if you are planning to perform
QM/MM calculations with large numbers of classical centres.
For Intel compilers the recommended configure.dat line is:
intel15.0 parallel base mpi mpiwrap newscf chemshell qmmm large mkl_scalapack scalapack
Then compile with:
./configure -e
make
(making sure the paths etc. in your .mk file are correct first)
Task-farming parallelisation with GAMESS-UK is fully supported by ChemShell.
-- NWChem library --
The libraries required by ChemShell are created as part of the standard
NWChem build process. NWChem should be compiled with:
USE_64TO32=y
so that the library calls are compatible with ChemShell (and GULP).
Alternatively, ChemShell can be compiled with 8-byte integers,
but this approach is not recommended.
Task-farming parallelisation with NWChem is supported as of ChemShell 3.7.
-- (LS)Dalton library --
To build Dalton or LSDalton as a library for ChemShell, pass the
argument -DENABLE_CHEMSHELL=ON to the setup script. The recommended setup
line is:
./setup --fc=... -cc=... -cxx=... --mpi --scalapack -DENABLE_CHEMSHELL=ON build
ChemShell 3.7 supports linking with (fully patched) Dalton 2016, or LSDalton 2020.
Task-farming parallelisation is supported only with LSDalton.
-- GULP library --
GULP version 6.1 or later can be linked directly into ChemShell.
The mkgulp script should be used to compile GULP as a library.
For example for an Intel MPI library build use:
./mkgulp -c intel -m -t lib
If necessary remove lapack.o from MLIBS in mkgulp as ChemShell provides LAPACK.
NB In GULP v6.2 an additional build option lib-nomaths has been introduced
which should be used instead of lib
The compilation process should produce the file libgulp.a. ChemShell expects
to find this file at the top of the GULP tree, and it may need to be moved there
manually if your version of mkgulp does not do this automatically (depending
on your GULP version).
GULP can be built into ChemShell together with any of the above QM codes.
3. Configuration of ChemShell
=============================
3.0. Unpacking the program
The software may be built in any convenient location and at present there
is no automated way to move binaries to a separate installation directory.
it is assumed that the program will be executed from the build location.
Unpack the distribution file using the GNU compression utility
(gunzip) and the Unix tar command.
Typically this involves (eg on linux machines)
% tar -xvzf chemsh-3.7.0.tar.gz
This will create a root directory (typically chemsh) with number of
subdirectories including scripts, src, bin and tcl. The root
directory and its contents should then be moved to the required
destination.
3.1. Make sure you have Tcl libraries and include files
available (see above)
Then set the TCLROOT variable to point to the directory
containing the relevant lib, include etc. If you are using
system version TCLROOT can be set to a system directory,
such as /usr . ChemShell expects the files $TCLROOT/lib/libtcl8.5.so
and $TCLROOT/include/tcl.h to be present.
If you are using Tcl 8.4 or 8.6, set LIBTCL also (as by default this will
reference Tcl8.5). It can be set directly to the path of the .so, e.g.:
export TCLROOT=/home/username/tcl/tcl8.6.6
export LIBTCL=/home/username/tcl/tcl8.6.6/lib/libtcl8.6.so
3.2. Choose your C and Fortran compilers
Set the CC, F77, F90 environment variables
IMPORTANT NOTE - the use of F77 and F90 variables is perhaps not
what you might expect.
The F77 variable should point to a compiler which can compile
Fortran 90 code, but is expecting it in "traditional" F77 fixed
format.
The F90 variable should point to a compile which, when presented
with a file with a .f90 suffix, will expect it to contain code
in the modern free format.
For example, when using GNU Fortran, set both to gfortran.
When using Portland Group compilers, set both to pgf90.
When using the Intel compiler, set both to ifort.
When using IBM xlf compilers, set F77 to xlf and F90 to xlf90.
3.3. If a direct link to GAMESS-UK, NWChem, (LS)Dalton, FHI-aims or
GULP is needed, build these codes to generate libraries (see above).
3.4. Run the configure script
The following options are available:
--with-mpi
Parallel MPI version of ChemShell
--with-gamess-uk=
Link in GAMESS-UK libraries
--with-peigs
Use the PeIGS parallel diagonaliser in GAMESS-UK
(GAMESS-UK should be built with the keywords "peigs ma").
In general not recommended as scalapack gives better performance.
--with-nwchem
Link in NWChem libraries specified by NWCHEM_TOP and NWCHEM_TARGET
--with-ga=
Specify Global Arrays library for use with NWChem builds.
(Not recommended for GAMESS-UK, use mpi/scalapack instead.)
--with-dalton=
Link in DALTON libraries
--with-lsdalton=
Link in LSDalton libraries
--with-aims=
Link in FHI-aims
--with-gulp=
Link in GULP libraries
--with-integer8
Compile with 8-byte integers
3.5 Variable settings
With Tcl version 8.5 and above the code will used shared libraries
(.so files) on most systems, and this may require the setting of
additional environment variables, e.g. LD_LIBRARY_PATH, depending on
your platform. The variable should refer to the
lib subdirectory of tcl8 (which should contain the .so files.
export PATH=[root dir]/bin:[root dir]/scripts:$PATH
3.6 DL-FIND
ChemShell 3.2 and newer is supposed to be compiled with DL-FIND. It
will generally be supplied with ChemShell, but if you have received a
copy without a directory called src/dl-find, contact the ChemShell
developers. Alternatively, you can delete the reference to dl-find in
src/config/configure.
3.7 (Developers) Cloning from the ChemShell repository
If you are downloading ChemShell from the STFC git repository please
make sure to clone recursively as follows:
git clone --recursive
The --recursive argument ensures that the DL-FIND submodule will be
checked out together with the main ChemShell project.
4. Compilation
==============
Now all the Makefiles and prerequisites are generated the make
command should be issued in the [root dir]/src directory.
Note that the make command does not lead
to any updating of sub-makefiles, and if new modules are added
the configuration process must be repeated.
5. Additional Installation Steps
================================
If your system has alternate names for the installation directory, you
may wish to edit [root dir]/scripts/chemsh to use the
alternative names. This can occur if a number of machines share a
filesystem by NFS. If chemsh is to be run on all hosts, it is
important that the library files are accessed by a "standardised"
pathname that is valid on all hosts. By default, chemsh will build to
work on the compilation host.
6. Some Sample Builds
=====================
Simple Serial Workstation build
-------------------------------
In favourable cases, after building Tcl the ChemShell configuration is
performed as follows:
(assumes Tcl configured with --prefix=/usr/username/tcl/tcl8.5.11).
export TCLROOT=/usr/username/tcl/tcl8.5.11
export CC=cc
export F77=f90
export F90=f90
./configure
Using the Intel Compiler (ifort)
--------------------------------
Some difficulties with linking system Tcl libraries have been reported
in the past. We recommend that you build Tcl from source and
specify the library explicitly with LIBTCL:
#
# Sample build configuration for EM64-T / ifort
#
export CC=icc
export F77=ifort
export F90=ifort
export TCLROOT=/usr/username/tcl/tcl8.5.11
export LIBTCL=/usr/username/tcl/tcl8.5.11/lib/libtcl8.5.so
./configure
ChemShell 3.7 is tested with Intel 2017 update 1.
Using GNU compilers (gfortran)
------------------------------
Older versions of gfortran may cause problems. ChemShell 3.7 should
work with gfortran version 5.4.0 (20160609) or later.
gfortran version 10 or later by default checks strictly for argument
mismatches, which will cause compilation to fail. This behaviour
can be switched off using the compiler flag -fallow-argument-mismatch
as in the following example configuration:
export CC=gcc
export F77=gfortran
export F90=gfortran
export TCLROOT=/home/username/tcl/tcl8.6.8
export LIBTCL=/home/username/tcl/tcl8.6.8/lib/libtcl8.6.so
export FFLAGS=-fallow-argument-mismatch
export F90FLAGS=-fallow-argument-mismatch
Using the g95 compiler
----------------------
g95 requires configuring with ./configure --with-integer8
We do not test ChemShell with g95 and recommend the official GCC
compiler gfortran instead.
MPI build using wrapper compilers
---------------------------------
When using wrapper compilers the underlying Fortran compiler should be
specified explicitly using the environment variable
COMPILER_IS_PGI/INTEL/GFORTRAN/G95 = 1.
For example, our testing MPI build using GNU/OpenMPI is configured
as follows:
export PROJECTDIR=...
export CC=mpicc
export F77=mpifort
export F90=mpifort
export COMPILER_IS_GFORTRAN=1
export TCLROOT=$PROJECTDIR/tcl8.5.11
export LIBTCL=$PROJECTDIR/tcl8.5.11/lib/libtcl8.5.so
# Directly link GULP
./configure --with-mpi --with-gulp=$PROJECTDIR/gulp-4.5
Intel MPI build with MKL Scalapack for GAMESS-UK
------------------------------------------------
export CC=mpiicc
export F77=mpiifort
export F90=mpiifort
export COMPILER_IS_INTEL=1
export MKLDIR=/opt/intel/compilers_and_libraries_2017.1.132/linux/mkl/lib/intel64
export LDFLAGS="-L${MKLDIR} -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core -lpthread -lm -lmkl_scalapack_lp64 -lmkl_blacs_intelmpi_lp64 -qopenmp"
# MPI include path
export MPIINC="-I/opt/intel/compilers_and_libraries_2017.1.132/linux/mpi/intel64/include"
export TCLROOT=/home/username/tcl/tcl8.6.6
export LIBTCL=/home/username/tcl/tcl8.6.6/lib/libtcl8.6.so
# Link in GAMESS-UK and GULP libraries
./configure --with-mpi --with-gulp=... --with-gamess-uk=...
Intel MPI build with NWChem/GA
------------------------------
export CC=mpiicc
export F77=mpiifort
export F90=mpiifort
export COMPILER_IS_INTEL=1
# For NWChem 6.6
export LDFLAGS="-qopenmp"
# MPI include path
export MPIINC="-I/opt/intel/compilers_and_libraries_2017.1.132/linux/mpi/intel64/include"
export TCLROOT=/home/username/tcl/tcl8.6.6
export LIBTCL=/home/username/tcl/tcl8.6.6/lib/libtcl8.6.so
export NWCHEM_TOP=/home/username/nwchem/nwchem-6.6-ifort17u1-64to32
export NWCHEM_TARGET=LINUX64
# Configure with MPI, GA, NWChem, GULP
./configure --with-mpi --with-ga=${NWCHEM_TOP}/src/tools/install --with-nwchem --with-gulp=...
Intel MPI build with LSDalton and MKL Scalapack
-----------------------------------------------
export CC=mpiicc
export F77=mpiifort
export F90=mpiifort
export COMPILER_IS_INTEL=1
export MKLDIR=/opt/intel/compilers_and_libraries_2017.1.132/linux/mkl/lib/intel64
# LSDalton requires C++ standard library
export LDFLAGS="-L${MKLDIR} -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core -lpthread -lm -lmkl_scalapack_lp64 -lmkl_blacs_intelmpi_lp64 -qopenmp -lstdc++ -lz"
# MPI include path
export MPIINC="-I/opt/intel/compilers_and_libraries_2017.1.132/linux/mpi/intel64/include"
export TCLROOT=/home/username/dev/tcl/tcl8.5.11
export LIBTCL=/home/username/dev/tcl/tcl8.5.11/lib/libtcl8.5.so
# Configure with MPI, LSDalton
./configure --with-mpi --with-lsdalton=...
7. Verifying Compilation
========================
To check that a serial build of ChemShell has compiled properly,
go to the examples/ directory and run:
./run_validation.tcsh
All the tests should return either pass (P), unsupported (M) or
"unknown" (U). M means that you do not have an external program
required to run the test, while U tests have no explicit success
criterion besides not crashing.
If any of the tests fail (F) there is likely a problem with the
the compiled executable.
Parallel builds can be verified with:
../scripts/chemsh -p 4 validate_buildbot.chm
which runs a similar set of tests over 4 processes.
|
