.. _install:

********************
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                  || 7.3          ||      |
|                         || OR icc/ifort                  || 17           ||      |
+-------------------------+--------------------------------+---------------+-------+
| ChemShell (parallel)    || mpicc.openmpi/mpifort.openmpi ||              ||      |
|                         || OR mpiicc/mpiifort            || 17           ||      |
+-------------------------+--------------------------------+---------------+-------+
| ChemShell (all)         || cmake                         || 3.16         ||      |
|                         || python3-dev                   || 3.8          ||      |
|                         || python3-numpy                 || 1.21.5       ||      |
|                         || git                           || 2.16         || [a]_ |
|                         || libblas-dev/liblapack-dev     ||              || [b]_ |
|                         || OR Intel MKL                  ||              ||      |
+-------------------------+--------------------------------+---------------+-------+
| ChemShell (plotting)    || matplotlib, tkinter           ||              || [c]_ |
|                         || AND its dependencies: cycler, ||              ||      |
|                         || pyparsing, Pillow,            ||              ||      |
|                         || python_dateutil, kiwisolver,  ||              ||      |
|                         || six                           ||              ||      |
+-------------------------+--------------------------------+---------------+-------+
| 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++                           || 7.3          ||      |
|                         || OR icpc                       || 17           ||      |
|                         || libqt5core5a/libqt5widgets5/  ||              || [f]_ |
|                         || libqt5gui5/readline-common/   ||              ||      |
|                         || libqt5printsupport5/bison/    ||              ||      |
|                         || libfreetype6/libglu1-mesa/    ||              ||      |
|                         || libegl1-mesa/libftgl2         ||              ||      |
+-------------------------+--------------------------------+---------------+-------+
| PDB2PQR                 || pandas                        || 1.0.5        || [g]_ |
|                         || mmcif_pdbx                    ||              ||      |
|                         || pytz, python-dateutil, six    ||              ||      |
|                         || AND requests                  ||              ||      |
+-------------------------+--------------------------------+---------------+-------+
| 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


.. _install_namd:

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


.. _install_nwchem:

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
=========================

.. _install_charmm_ff:


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 <http://mackerell.umaryland.edu/charmm_ff.shtml>`__) 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 <https://github.com/Electrostatics/pdb2pqr.git>`__) 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] 

