From tinkergpu
Revision as of 04:49, 17 December 2020 by Liuchw (talk | contribs)
Jump to navigation Jump to search


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.   

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 python=3.7
  conda activate FB17
  conda install --strict-channel-priority -c conda-forge forcebalance

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


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). 

├── 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. 

├── 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 


Customization and parallelization for AMOEBA(+)

1. Backup original FB source files

  export condaHOME = /home/liuchw/anaconda3/envs/FB17/lib/python3.7/site-packages/forcebalance
  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/Tinker-OpenMM dynamic jobs

3. An extra file besides the .in is needed in order to distribute the dynamic/dynamic_omm jobs on to different Renlab cluster nodes. Specify the node filename in the .in file as

 liquid_node yourfilename.node

where the yourfilename.node should look like:

Liquid_Methanol       278.15 node78
Liquid_Methanol       298.15 node49
Liquid_Methanol       318.15 node79
Liquid_Ethanol        278.15 node83
Liquid_Ethanol        298.15 node73
Liquid_Ethanol        318.15 node55
Liquid_1-Propanol     278.15 node54
Liquid_1-Propanol     298.15 node47
Liquid_1-Propanol     318.15 node40
Liquid_2-Propanol     278.15 node44
Liquid_2-Propanol     298.15 node53
Liquid_2-Propanol     318.15 node85
Liquid_Methane         95.15 node72
Liquid_Methane        105.15 node61
Liquid_Ethane         154.15 node43
Liquid_Ethane         174.15 node42