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/liuchw/FB-demo" for local files.

ForceBalance Installation

ForceBalance can be installed in different ways. Here I recommend installing FB through conda software manager (either Anaconda or Miniconda). For how to install conda, please go to the anaconda download page (https://www.anaconda.com/products/individual).

After you have conda installed, FB can be easily installed through the following commands:

  conda create --name FB17
  conda activate FB17
  conda install forcebalance=1.7.5

Note that in the above we installed forcebalance version 1.7.5. If you need new features beyond this version, just remove "=1.7.5" in the above installation. Now ForceBalance is installed. You should be able to run (but not efficiently) FB jobs with the following settings.

ForceBalance input files

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

/home/liuchw/FB-demo/015_amoeba_tinker

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, you should be able to run ForceBalance using the simple command:

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

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.