Installing ChemShell

ChemShell is compiled using the setup script in the top level directory.

Prerequisites

The table below outlines the requirements when building ChemShell and linking with external QM and MM software packages. The required tools and libraries are cumulative, i.e. to build ChemShell with GAMESS-UK one needs both appropriate compilers, maths libraries and the m4 package. Unless explicitly stated, all tools and libraries outlined are for parallel compilations.

Software (build)	Tools & Libraries	Min. version	Note
ChemShell (serial)	gcc/gfortran OR icc/ifort	7.3 17
ChemShell (parallel)	mpicc.openmpi/mpifort.openmpi OR mpiicc/mpiifort	17
ChemShell (all)	cmake python3-dev python3-numpy git libblas-dev/liblapack-dev OR Intel MKL	3.16 3.8 1.21.5 2.16	[a] [b]
ChemShell (plotting)	matplotlib, tkinter AND its dependencies: cycler, pyparsing, Pillow, python_dateutil, kiwisolver, six		[c]
CP2K	libfftw3-dev OR Intel FFTW3
GAMESS-UK	m4
GULP	libscalapack OR Intel MKL		[d]
LSDalton	mpiicpc, Intel MKL	17
NAMD	g++, libfftw3-dev OR mpiicpc, Intel FFTW3	17
NWChem		17	[e]
Aten	g++ OR icpc libqt5core5a/libqt5widgets5/ libqt5gui5/readline-common/ libqt5printsupport5/bison/ libfreetype6/libglu1-mesa/ libegl1-mesa/libftgl2	7.3 17	[f]
PDB2PQR	pandas mmcif_pdbx pytz, python-dateutil, six AND requests	1.0.5	[g]
Documentation	python3-sphinx python3-sphinx-rtd-theme

NB

The above package names are based on Ubuntu Linux. They may vary on other operating systems.

a

Only required when cloning directly from the ChemShell repository. Use git clone --recursive to download ChemShell and DL-FIND together.

b

For GNU and Intel compilers, respectively

c

When the internet is available ChemShell will install these Python dependencies locally (to the ChemShell folder) using the pip command. Most Python3 distributions should already contain tkinter which is a standard Python libray; if this is not the case, for example on Ubuntu, python3-tk should be installed

d

Since GULP 5.0, for GNU and Intel compilers, respectively

e

Since NWChem 7.0

f

Please see: https://github.com/trisyoungs/aten

g

When the internet is available ChemShell will install these Python dependencies locally (to the ChemShell folder) using the pip command

Compiling ChemShell

Please see the detailed instructions below for the platform of your choice.

Linux desktop (e.g. Ubuntu)

To print the helper:

$ ./setup -h

To compile a serial build with Intel:

$ ./setup --fc ifort --cc icc

To compile a serial build with GNU:

$ ./setup --fc gfortran --cc gcc

To compile a parallel build with Intel MPI:

$ ./setup --mpi --fc mpiifort --cc mpiicc

To compile a parallel build with GNU/OpenMPI:

$ ./setup --mpi --fc mpifort.openmpi --cc mpicc.openmpi

HINT

All commands previously used for building ChemShell are saved in a local file: _chemsh_build.log

ARCHER2 (GNU programming environment)

Compile ChemShell with the platform option to provide settings for ARCHER2:

$ ./setup --platform archer2

Other HPC platforms

Typically commands similar to the above are needed:

$ module load YOUR_PYTHON3_MODULE

$ ./setup --platform YOUR_PLATFORM

Please contact us if a preset is not yet available for your HPC platform of choice.

Optional linking to external codes

Most ChemShell-interfaced codes can either be called via system commands or invoked as a directly-linked library (when source code is provided). The latter is highly recommended on HPC systems to gain the best parallel performance. You can specify one or more codes of your choice in addition to the above arguments. Then a typical command to compile ChemShell with directly-linked libraries is:

$ ./setup --mpi --fc mpiifort --cc mpiicc --cpc mpiicpc --dl_poly YOUR_DLP4_LOCATION \
          --gulp YOUR_GULP_LOCATION --gamess-uk YOUR_GAMESS-UK_LOCATION \
          --nwchem YOUR_NWCHEM_LOCATION --fhiaims YOUR_FHIAIMS_LOCATION

Please see the detailed instructions below for the codes of your choice.

CASTEP

CASTEP version 23.1.1 or above can be directly linked with Chemshell. The CASTEP source code should be obtained prior to the linking.

To compile Chemshell with CASTEP linked in, either,

Pre-compile CASTEP independently with the command:

``make [other options] castep_lib``

A library file libcastep.so is generated in the directory obj/platform/lib. Provide the full path to this file in the Chemshell install command with the --castep argument:

``./setup --castep FULL_PATH_TO_LIBCASTEP.SO``

Alternatively, simply use:

``./setup --castep PATH_TO_CASTEP_ROOT_DIRECTORY``

Chemshell compiles parallel CASTEP with the default system settings, and links the generated CASTEP library.

CP2K

ChemShell supports directly linked CP2K v2022 or later, which can be downloaded and compiled if the internet is accessible, via command line argument of ./setup:

--cp2k

DL_POLY 5

DL_POLY v5 or later may be linked to ChemShell. DL_POLY Classic is not supported. To let ChemShell download the source code from the official DL_POLY repository and compile and link to ChemShell, simply use the argument:

--dl_poly

Alternatively, DL_POLY 5 can also be automatically compiled by and directly-linked to ChemShell if a tarball or a directory containing the source code is available:

--dl_poly YOUR_DLP5_TARBALL

or:

--dl_poly YOUR_DLP5_DIR

DL_FIELD

DL_FIELD prepares forcefield parameters for DL_POLY-based calculations and is necessary for ChemShell’s workflow for biomolecular QM/MM modelling. DL_FIELD must currently be registered and downloaded from: http://www.ccp5.ac.uk/DL_FIELD. To compile and link DL_FIELD (v4.8 or later) in ChemShell, run ./setup with the following argument providing the root path to pre-downloaded DL_FIELD source dir:

--dl_field YOUR_DLFLD_DIR

FHI-aims

FHI-aims compilations datestamped 2018 or later can be linked to ChemShell.

FHI-aims will NOT be compiled on the fly by ChemShell. One needs to compile FHI-aims as a shared library; within the FHI-aims source directory, this can be achieved via: - a Makefile build with make libaims.mpi or the ScaLAPACK equivalent, make libaims.scalapack.mpi; - alternatively, one can use CMake and include the flag BUILD_SHARED_LIBS ON CACHE STRING "". In both instances -fPIC must be included in your compilation flags.

The precise address of the shared library is then passed to ChemShell setup with:

--fhiaims YOUR_FHIAIMS_LOCATION

GAMESS-UK

GAMESS-UK 8, r6325 or later can be linked to ChemShell. We do not yet support GAMESS-UK builds with GNU compilers.

GAMESS-UK 8 is automatically compiled by and directly-linked to ChemShell if a directory containing the source code is available:

--gamess-uk YOUR_GAMESS-UK_DIR

GULP

GULP v6.1.0 or later can be linked to ChemShell.

GULP is automatically compiled by and directly-linked to ChemShell if a tarball or a directory containing the source code is available:

--gulp YOUR_GULP_TARBALL

or:

--gulp YOUR_GULP_DIR

LSDalton

LSDalton release/2020 can be directly linked to ChemShell.

LSDalton is not compiled automatically by ChemShell and should be compiled using its own setup script first as follows:

$ export MATH_ROOT=[path to Intel MKL]
$ ./setup -fc=mpiifort --cc=mpiicc --cxx=mpiicpc --mpi --scalapack -DENABLE_CHEMSHELL=ON \
     --extra-fc-flags="-fPIC" --extra-cc-flags="-fPIC" --extra-cxx-flags="-fPIC" build

LSDalton can then be linked into ChemShell using the flag:

--lsdalton YOUR_LSDALTON_DIR/build

NAMD

ChemShell can compile NAMD 2.14 or later (including its parallel driver Charm+, not to be confused with CHARMM) using the following argument provided a path to pre-downloaded zipped source files or extracted source directory is given:

--namd NAMD_2.14_Source.tar.gz

or:

-namd YOUR_NAMD_PATH

Note

A parallel NAMD should only be compiled with the existenc of either OpenMPI or Intel MPI. NAMD does not run if they coexist on your system. You must uninstall or unload (via Environment Modules) either of them.

Please also note that NAMD will not be linked to ChemShell via direct memory manipulation. Instead, invoking system calls to the NAMD executable binary is the working mechanism. Parallel calculations driven by Charm+ is fully supported and the arguments are automatically managed by ChemShell. The performance has been proved to be very high on various HPC platforms.

FFTW is needed by NAMD, for example from Intel MKL 2020 onwards:

--fftw /opt/intel/oneapi/mkl/latest/interfaces/fftw3xf --fftw_include_dir /opt/intel/oneapi/mkl/latest/include/fftw

NWChem

NWChem 7.0 or later can be linked to ChemShell. Neither serial nor GNU-compiled build has been tested. The NWChem source code does not have to be downloaded beforehand. You only need to use the following argument to ask ChemShell to download (default version 7.2.2) from the official NWChem repository and compile it on the fly:

--nwchem

Note

This procedure may typically take up to an hour or even longer. Please be patient util the build is done.

Alternatively, NWChem can be compiled by hand separately if a directory containing the source code is provided:

--nwchem YOUR_NWCHEM_DIR

ChemShell inspects if this NWChem source package is already pre-compiled and if not it will generate a compile script in YOUR_NWCHEM_LOCATION/src containing all required system environtment settings , for example:

compile_nwchem_7.0_for_chemsh_on_XXXX.sh

Hint

$ ./setup -j NCPUS_TO_USE_FOR_COMPILE can be used to speed up the NWChem compile depending on the nubmer of CPU cores and Intel licence on your computer)

Then please run the above script until it finishes:

$ cd YOUR_NWCHEM_LOCATION/src

$ ./compile_nwchem_7.0_for_chemsh_on_XXXX.sh &

Now NWChem should be compiled and can be directly-linked to ChemShell. Go back to your ChemShell source package and rerun ./setup with:

--nwchem YOUR_NWCHEM_LOCATION

Optional external add-ons

CHARMM forcefield data

The standard CHARMM forcefield data (not to be confused with the CHARMM program) for the biomolecular workflows can be installed at compile time with the argument:

--charmm-ff

For computers where the internet is unavailable, do not use the above --charmm-ff argument. Instead, copy or extract pre-downloaded CHARMM forcefield directory (download from here) to your ChemShell. For example, if you downloaded version c36_jul21 (2021), the destination directory should be YOUR_CHEMSH/chemsh/data/charmm/c36_jul21 where c36_jul21 is the root directory of CHARMM forcefield containing file topar and subdirectory toppar_c36_jul21. For versions before 2021, such as c36_jul18 (2018), the destination directory should be

YOUR_CHEMSH/chemsh/data/charmm/c36_jul18

where c36_jul18 must contain files such as top_all36_prot.rtf and par_all36m_prot.prm.

PDB2PQR

PDB2PQR is strongly recommended to be used for the Protein Solvation workflow. Use the following command line argument with ./setup to install PDB2PQR in ChemShell (access to the internet is required):

--pdb2pqr

For computers where the internet is unavailable, do not use the above --pdb2pqr argument. Instead, copy or extract pre-downloaded PDB2PQR v3.5.2 source directory (download from here) to your ChemShell as

YOUR_CHEMSH/chemsh/addons/pdb2pqr/src

where src should be the root directory of PDB2PQR (namely, containing files such as LICENSE.md, README.md, and setup.py). Then, run:

$ cd YOUR_CHEMSH/chemsh/addons/pdb2pqr/src
$ python3 setup.py build

Basis Set Exchange (MolSSI-BSE)

ChemShell supports integration with the MolSSI/EMSL Basis Set Exchange (BSE) library. By installing the BSE add-on you can easily set up the basis set, especially the hybrid ones, in your QM or QM/MM calculations. The installation argument for the ./setup command is:

--bse

For computers where the internet is unavailable, do not use the --bse argument, but download the source code from https://github.com/MolSSI-BSE/basis_set_exchange (version 0.9) to your ChemShell destination

YOUR_CHEMSH/chemsh/addons/molssi_bse/src

where src should be the root directory of BSE containing files LICENSE, README.md, and setup.py. Then, run:

$ cd YOUR_CHEMSH/chemsh/addons/molssi_bse/src
$ python3 setup.py build

Clean and recompile

To clean up an existing build (the cleanup is not guaranteed to be 100% complete):

$ ./setup --clean -fc gfortran/ifort [default is ifort]

To recompile one or more modules or external codes, for example:

$ ./setup --rebuild ga gamess-uk dl_poly [OTHER_ARGUMENTS]