UWHAM

Table of Contents

1 how to install

2 list of options:

  simple description default
h print out help information -
d potential energy input file -
t temperature 300
g GROMACS input format -1
i unit of potential energies in the input file 0
o unit of free energies of the output 0
m iteration method 0
q length of the equilibrium period 1
n number of iterations 1.0e10
e error tolerance -
w print list of weights none
z normalization no

2.1 options and descriptions

2.1.1 -d potential_energy_input_file

This file contains \(M\) blocks, which correspond to \(M\) \(\lambda\)-states. At the beginning of each block, there is a comment line or multiple comment lines starting with "@" or "#". Do not leave blank lines between blocks. After comments lines, there is a \(N_i \times M\) matrix, where \(N_i\) is the total number of observations observed at the \(i^{th}\) \(\lambda\)-state. The matrix element \(p_{jk}\) of the \(i^{th}\) block is the potential energy (or potential energy difference, see discussion below) of the \(j^{th}\) observation (observed at the \(i^{th}\) \(\lambda\)-state) at the \(k^{th}\) \(\lambda\)-state. The default unit of potential energies is \(k_B T\). See option "-i" and "-o" for using a different unit for energy.
Suppose all information is stored in a three dimensional array "D", where \(D[i][j][k]\) is the element at the \(j^{th}\) row and the \(k^{th}\) column of the matrix in the \(i^{th}\) block of the input file. The default value of \(D[i][j][k]\) is the potential energy of the \(j^{th}\) observation observed at the \(i^{th}\) \(\lambda\)-state calculated with the Hamiltonian function of the \(k^{th}\) \(\lambda\)-state — \(P[i][j][k]\). Note that the essential information for the UWHAM analysis is the difference of the potential energies of the same observation at different \(\lambda\)-states. Therefore, the UWHAM results will remain the same if one applies a constant energy shift for each observation, namely \(D[i][j][k] = P[i][j][k] - C[i][j]\), where \(C[i][j]\) is the shift. For example, when using UWHAM to analyze the data generated by Umbrella sampling, \(D[i][j][k]\) is usually the biasing potential energy instead of the total potential energy. Here is another example: when the outputs of free energy perturbation simulation of GROMACS (see option "-g") are used as the input for UWHAM, \(D[i][j][i]\) is always shifted to be zero.

2.1.2 -i input_unit -o output_unit

The default unit of potential energies used in UWHAM is \(k_B T\). However, if the data were generated by simulations running at a single temperature, UWHAM program can read and output energies in a different unit. The option "-i" specifies the unit used in the input; and the option "-o" specifies the unit used in the output. For these two options, "0" represents \(k_B T\); "1" represents \(kcal/mol\); and "2" represents "kJ/mol".

2.1.3 -t temperature

The temperature of simulations. This option is only meaningful when all the simulations are run at a single temperature and the units of the input and output are not \(k_B T\). When using UWHAM to analyze data generated by simulations run at different temperatures such as temperature replica exchange simulations, the input data in the potential energy input file (see option "-d") must be converted in unit of \(k_B T\).

2.1.4 -g GROMACS_format

This option is for GROMACS users. Free energy perturbation simulations of GROMACS provide all the data required by the potential energy input file (see option "-d"). The information is stored in the "xvg" file of each \(\lambda\)-state. One can use "cat" to combine all these "xvg" files together to generate an input file for the "-d" option. When "GROMACS_format" is non-negative (0 for NVT system, and 1 for NPT system), UWHAM will automatically extract the required information from the input file and set input_unit to "2" (namely "kJ/mol", see option "-i").

2.1.5 -m iteration_method

Two iteration methods have been implemented in this uwham program

  1. -m 0: self-consistent iteration

    This is the basic iteration method, which is slow but robust, and uses less memory. It calculates the density of states based on previous values of partition functions, then calculates the partition functions bases on the density of states, so on and so forth.

  2. -m 1: Convex Newton-Raphson

    This method optimize the convex function by Newton-Raphson algorithm.1. It converges much faster than the self-consistent iterations, but it is less stable and uses more memory. The Newton-Raphson solver needs the GNU scientific library for the matrix inversion.

2.1.6 -q equilibrium_length

A good initial guess of partition function (free energy differences) and density of states is critical for the Newton-Raphson solver to converge. This UWHAM program uses the "self-consistent iteration" method to obtain the initial guesses for the Newton-Raphson solver. The number assigned to the option "-q" decides how many self-consistent iterations run before using the Newton-Raphson solver to minimize the convex function. The UWHAM program will double the number of self-consistent iterations automatically if the Newton-Raphson algorithm fails to converge.

2.1.7 -e tolerance_error -n iteration_number

At the end of each iteration, the UWHAM program calculates the changes of free energy estimates

\begin{equation} \Delta f = \left | \frac {f_{new} - f_{old}}{f_{old}} \right | \end{equation}

for each \(\lambda\)-state. If all the \(\Delta f\) are smaller than the tolerance_error or the number of iteration is larger than the "iteration_number", the UWHAM program will stop and write the output.

2.1.8 -w print_list_of_weights

"print_list_of_weights" is a list of \(\lambda\)-states. For example, "1,3,5" means the first, the third and the fifth \(\lambda\)-states; "2-4" represents the second, the third and the fourth \(\lambda\)-states; and "1,3-5,9" represents the first, the third, the fourth, the fifth and the ninth \(\lambda\)-states. Note the number of \(\lambda\)-state starts from one, not zero. At the end of UWHAM calculation, the weights of each observation, which denotes the relative probability of observing each observation, at the states in the print_list_of_weights will be printed out in the "weights.data" file. The matrix in "weights.data" has \(N\) rows and \(m\) columns, where \(N\) is the total number of observations, and \(m\) is the total number of \(\lambda\)-states in the print_list_of_weights. If "print_list_of_weights" contains one single value zero (-w 0), for each observation, only the weight of that observation at the \(\lambda\)-state which it was observed will be printed out in the "weights.data" file. In default no weights will be printed out.

2.1.9 -z (normalization)

This option is a switch to normalize the weights for each \(\lambda\)-state. In default the weights are not normalized.

Footnotes:

1

Theory of binless multi-state free energy estimation with applications to protein-ligand binding (link)

Author: Bin Zhang

Created: 2018-05-03 Thu 11:39

Validate