Software:forcebalance

Background

ForceBalance is an automatic force field parametrization tool developed by Lee-Ping Wang et al. It allows one to use both quantum chemical data and experimental observables of the liquid phase. It has been applied to parameterize a bunch of water models and organic molecules. The following examples are some of them.

J. Phys. Chem. Lett., 2014, 5 (11), pp 1885–1891 (ForceBalance paper, TIP3P and TIP4P water as examples)

J. Phys. Chem. B, 2013, 117 (34), pp 9956–9972 (iAMOEBA paper)

J. Phys. Chem. B, 2015, 119 (29), pp 9423–9437 (AMOEBA14 paper)

Here, a brief tutorial on how to install, set up, parallelize and run FB is provided below.   

See "/home/yw24267/FB-demo" for local files.

ForceBalance Installation

To make ForceBalance work better on Ren lab cluster, a great amount of modifications have been made based on version 1.7.5, which is recorded at https://github.com/leucinw/Software-mod. To install ForceBalance 1.7.5 along with all the modifications, run the following first.

git clone https://github.com/leucinw/Software-mod.git 
cd Software-mod/forcebalance-1.7.5

The installer requires conda. For how to install conda, please go to the anaconda download page (https://www.anaconda.com/products/individual). Then, open `installer.sh` and modify the variables at the beginning of the script to fit your case. You may also want to read Software-mod/forcebalance-1.7.5/README.md for details before you continue. Then, simply running the following will complete the whole installation and patching for you.

bash installer.sh

If you need the original ForceBalance, it can be installed with conda directly.

conda create --name FB forcebalance -c conda-forge

Note that this will install the latest version without any modification for Ren lab cluster. See the official documentation for more installation methods.

ForceBalance input files

In the following I will use amoeba water as an example. All the files are located in Renlab cluster at

/home/yw24267/FB-demo

A  typical job of ForceBalance folder looks like: 

├── example.in
├── forcefield
│   └── water.prm
└── targets
    ├── DimerMin
    ├── Interactions_CCSDT
    ├── Interactions_MP2
    ├── Liquid
    ├── Monomer_Moments
    ├── Monomer_Vibration
    ├── cluster-02
    ├── cluster-03

where example.in has the settings read by ForceBalance, forcefield directory contains the tinker parameter file, and targets folder contains lots of targets (both QM and Liquid). 

Inside the QM target is the tinker xyz and interactions.txt, interactions.key files Inside the Liquid target are the input files for Tinker (key and xyz) and experimental data (data.csv). 

 Liquid/
├── data.csv
├── gas.key
├── gas.xyz
├── liquid.key
└── liquid.xyz

A cluster folder typically contains the XYZ files, interactions.key, and interactions.txt, which defines the QM reference and how you calculate the interaction energy for AMOEBA.

A QM target folder (showing below) typically contains xyz files, interactions.key and interactions.txt, which defines the QM reference and how you calculate the interaction energy for AMOEBA. 

Interactions_CCSDT/
├── 01-Prism.xyz
├── 02-Cage.xyz
├── 03-Bag.xyz
├── 04-Cyclic-Chair.xyz
├── 05-Book-1.xyz
├── 06-Book-2.xyz
├── 07-Cyclic-Boat-1.xyz
├── 08-Cyclic-Boat-2.xyz
├── interactions.key
├── interactions.txt
├── monomer_exp.xyz
├── monomer_mp2.xyz
├── monomer_opt.xyz

After setting up the above files, if you installed the modified version through the procedures stated above, you should be able to run ForceBalance using the following. Just make sure the tinkerpath in example.in is properly set! Note: The name of the bashrc file may vary depending what you set in the installer.sh file.

source ~/.bashrc.FB17
ForceBalance example.in

If ForceBalance jobs crash, check the error message and modify your setting.  More information about settings in the example.in, please refer to ForceBalance manual file 

http://leeping.github.io/forcebalance/doc/ForceBalance-Manual.pdf

Customization and parallelization for AMOEBA and AMOEBA+ force fields

1. Backup original FB source files

  export condaHOME = /home/liuchw/anaconda3/envs/FB17/lib/python3.7/site-packages/forcebalance (change this accordingly)
  cp $condaHOME/binding.py $condaHOME/binding.py_back
  cp $condaHOME/liquid.py $condaHOME/liquid.py_back
  cp $condaHOME/tinkerio.py $condaHOME/tinkerio.py_back
  cp $condaHOME/parser.py $condaHOME/parser.py_back
  cp $condaHOME/data/npt.py $condaHOME/data/npt.py_back

2. Download modified files and copy them to the anaconda lib directory

  git clone git@github.com:leucinw/Software-mod.git modcode
  export modfileHOME=/home/liuchw/modcode/forcebalance-1.7.5
  cp $modfileHOME/binding.py $condaHOME/binding.py
  cp $modfileHOME/liquid.py  $condaHOME/liquid.py
  cp $modfileHOME/tinkerio.py $condaHOME/tinkerio.py
  cp $modfileHOME/parser.py $condaHOME/parser.py
  cp $modfileHOME/data/npt.py $condaHOME/data/npt.py
  cp $modfileHOME/minimum_match.py $condaHOME/minimum_match.py
  cp $modfileHOME/solvation.py $condaHOME/solvation.py

The above customization mostly involves supports for AMOEBA+ keywords and parallelization of the serial jobs in:

• Tinker binding energy calculations (minimize and analyze)
• Tinker post-MD analyze jobs
• Tinker/Tinker9 dynamic jobs

3. Set environmental variable TINKERPATH, and put the following files in the directory that $TINKERPATH points to

analyze minimize dynamic optimize submitTinker.py nodes.dat

where, `analyze`, `minimize`, `dynamic` and `optimize` are Tinker8 executables; `submitTinker.py` is downloaded from Software-mod in the previous step. This script is responsible for submitting Tinker CPU and GPU jobs on to Ren lab clusters. This script is reading node list from `nodes.dat` file, which looks like the following

#===========================================

#   Any line starts with "#" will be ignored.

#   Only the first two columns matter !!

#   This file is used by submitTinker.py

#===========================================

### GPU nodes mainly use

GPU node152   4090    2

GPU node154   4090    2

#CPU nodes nthreads

CPU      node145  32

CPU      node146  32

CPU      node152  64

CPU      node153  64

4. Set the .forcebalance.bashrc, please change accordingly

 #!/usr/bin/bash
 source ~/.bashrc
 conda activate FB17

 export TINKERPATH=/home/liuchw/bin/TinkerGPU2022
 export PATH=$PATH:$TINKERPATH

 VAL=`nvidia-smi &> /dev/null; echo $?`
 # check existence
 if [ $VALi!= 0 ]; then
   echo -e "   \e[101mCUDA utility not installed on `hostname`\e[0m"
 else
     export tk9home=/home/liuchw/Softwares/tinkers/Tinker9/2403/build
     export  DYNAMIC="$tk9home/dynamic9"
     export  ANALYZE="$tk9home/analyze9"
     export      BAR="$tk9home/bar9"
     export MINIMIZE="$tk9home/minimize9"
     export TESTGRAD="$tk9home/testgrad9"
 fi

# used by ForceBalance.py via
# os.environ["JOBPOOL"]
# os.environ["FBBASHRC"]
export JOBPOOL=/home/liuchw/bin/JobPool
export FBBASHRC=/home/liuchw/.forcebalanceOrganic

where there is another directory `JOBPOOL` needs to be set. In that directory, there are `subCPU.py` and `subGPU.py` which are keeping submitting the `*.sh` files appear in that directory. Please see `/home/liuchw/bin/JobPool` for detail. FBBASHRC is the absolute file path of the above bashrc file.