SWHAM

Table of Contents

1 how to install

  • compile:

    g++ swham.cpp -lm -o swham.o
    

2 list of options:

  simple description default
h print out help information -
d input file contains information of observations -
f input file contains information of states -
u type of the potential function -
t temperature -1.0
i unit of potential energies in the input file 0
o unit of free energies of the output 0
q length of the equilibrium period -
n number of the RE or ST cycles -
x number of exchange attempts in RE or jump attempts in ST 0(ST)/1(RE)
s list of states to print out -
p list of properties of each observation to print out 0
g frequency of printing free energy estimates 0
k input numbers are in units of one thousand -
m input numbers are in units of one million -
w estimate weights -

2.1 options and descriptions

2.1.1 -d observation_data_file

The "observation_data_file" contains information of observations. Like the input file for UWHAM, this file contains \(M\) blocks. Each block corresponds to a \(\lambda\)-state. 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 K\) matrix, where \(N_i\) is the total number of observations observed at the \(i^{th}\) state and \(K\) is the total number of properties of each observation. For example, to analyze the raw data generated by a temperature replica exchange simulation for the alanine dipeptide molecule in implicit solvent, the \(\phi\) and \(\psi\) angles and the potential energy of each observation can be the properties of observation recorded in "observation_data_file".

2.1.2 -f state_information_file

This file contains information of \(\lambda\)-states. There are \(M\) lines in this file and each line represents a \(\lambda\)-state. If the value of temperature defined by "-t" option is negative, the first number of each line is the temperature of that \(\lambda\)-state. Usually, the next item of each line can be the lambda value of that \(\lambda\)-state, see option '-u'.

2.1.3 -t temperature

The temperature of all the simulations. This option is only useful when the simulations are run at a single temperature. The default value of this option is \(-1\). If "temperature" is negative, the temperature of each state is defined by the first number of each line in the "state_information_file", see option "-f".

2.1.4 -u potential_function_type

The potential energy (biasing potential energy) need to be calculated for each observation at each \(\lambda\)-state. As shown in the following table, six different potential functions have been implemented in the SWHAM code. The potential function \(U[i][j][k]\) is the potential energy of the \(j^{th}\) observation observed at the \(i^{th}\) \(\lambda\)-state calculated by the Hamiltonian function of the \(k^{th}\) \(\lambda\)-state in unit of \(k_B T\).

type description potential function \(U[i][j][k]\)
0 UWHAM-like input \(D[i][j][k]/(K_B S[k][1])\)
1 Temperature replica exchange \(D[i][j][1]/(K_B S[k][1])\)
2 Hamiltonian replica exchange \(D[i][j][1] \times S[k][2]/(K_B S[k][1])\)
3 Temperature and Hamiltonian replica exchange \((D[i][j][1]+D[i][j][2] \times S[k][2])/(K_B S[k][1])\)
4 One dimensional umbrella sampling \((\frac{1}{2} \times S[k][2] \times (D[i][j][1] -S[k][3])^2)/(K_B S[k][1])\)
5 Two dimensional umbrella sampling \((\frac{1}{2} \times S[k][2] \times (D[i][j][1] -S[k][4])^2 + \frac{1}{2} \times S[k][3] \times (D[i][j][2] -S[k][5])^2)/(K_B S[k][1])\)

In this table, \(D[i][j][k]\) is the \(k^{th}\) property of the \(j^{th}\) observation observed at the \(i^{th}\) \(\lambda\)-state. \(S[k][1]\) is the first property, namely the temperature, of the \(k^{th}\) \(\lambda\)-state.

  1. UWHAM-like input (-u 0)

    This option allows the SWHAM program to use the UWHAM input, where \(D[i][j][k]\) is the potential energy of the \(j^{th}\) observation observed at the \(i^{th}\) \(\lambda\)-state calculated by the Hamiltonian function of the \(k^{th}\) \(\lambda\)-state. Therefore, each observation has at least \(M\) properties, where \(M\) is the total number of \(\lambda\)-states.

  2. Temperature replica exchange (-u 1)

    This potential function is implemented to analyze the data generated by temperature replica exchange (RE) simulations. In the "observation_data_file", the first property of each observation \(D[i][j][1]\) is the potential energy of that observation. Note in temperature RE simulations, the Hamiltonian functions of all \(\lambda\)-states are the same. More properties can be appended after the potential energy. In the "state_information_file", the first parameter (or property) of each state \(S[k][1]\) is the temperature of that state.

  3. Hamiltonian replica exchange (-u 2)

    This potential function is implemented to analyze the data generated by Hamiltonian replica exchange simulations. To use this type of potential function, the first property of each observation in the "observation_data_file" \(D[i][j][1]\) is the Hamiltonian energy part linearly controlled by the parameter \(\lambda\). In Hamiltonian RE simulations, all the simulations are run at the same temperature. Therefore, the temperature (\(S[k][1]\)) can be inputted by using the '-t' option. The first parameter of each state in the "state_information_file" (namely, \(S[k][2]\)) is the \(\lambda\) value of that \(\lambda\)-state.

  4. Temperature and Hamiltonian replica exchange (-u 3)

    This potential function is implemented to analyze the data generated by Temperature and Hamiltonian replica exchange simulations. The first property of each observation in the "observation_data_file" \(D[[i][j][1]\) is the Hamiltonian energy part which does not depend on the parameter \(\lambda\), and the second property of each observation \(D[i][j][2]\) is the Hamiltonian energy part which is controlled linearly by the parameter \(\lambda\). The first property of each state in the "state_information_file" \(S[k][1]\) is the temperature of that state, and the second property $S[k][2]$is the \(\lambda\) value of that state.

  5. One dimensional Umbrella Sampling (-u 4)

    This potential function is implemented to analyze the data generated by one dimensional umbrella sampling. The first property of each observation in the "observation_data_file" \(D[[i][j][1]\) is the reduced reaction coordinate of the observation. Suppose all the simulations are run at the same temperature. The temperature (\(S[k][1]\)) can be inputted by using the '-t' option. The first parameter of each state in the "state_information_file" (namely, \(S[k][2]\)) is the spring constant of the parabolic potential. The second parameter of each state is the minimum position of the parabolic potential. If the reduced reaction coordinate is periodic, the third parameter of each state is the period of the reaction coordinate.

  6. Two dimensional Umbrella Sampling (-u 5)

    This potential function is implemented to analyze the data generated by two dimensional umbrella sampling. The first and the second properties of each observation in the "observation_data_file" \(D[[i][j][1]\) and \(D[[i][j][2]\) are the first and the second reduced reaction coordinates of the observation respectively. Suppose all the simulations are run at the same temperature. The temperature (\(S[k][1]\)) can be inputted by using the '-t' option. The first and the second parameters of each state in the "state_information_file" (namely, \(S[k][2]\) and $S[k][3]) are the spring constants of the parabolic potentials in the first and the second dimensions respectively. The third and fourth parameters of each state in the "state_information_file" (namely, \(S[k][4]\) and $S[k][5]) are the minimum positions of the parabolic potentials in the first and the second dimensions respectively. If the reduced reaction coordinates are periodic, the fifth and sixth parameters of each state are the periods of the reaction coordinates.

2.1.5 -i input_unit -o output_unit

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

2.1.6 -q equilibrium_length

How many cycles to run to equilibrate the system. Both RE-SWHAM and ST-SWHAM are run by cycles. No results are printed out during the equilibrating period.

2.1.7 -n number_of_cycles

This option specifies how many cycles to be run after equilibrium.

2.1.8 -x number_of_exchange_attempts

This option specifies the number of exchange attempts in the exchange procedure of RE-SWHAM cycles. The default value of this option for RE-SWHAM is one. To reach the infinite exchange limit, a number between \(M^2\) and \(M^3\) is recommended, where \(M\) is the total number of \(\lambda\)-states of the system. This option is also been used to specify the number of jump attempts in the jump procedure of ST-SWHAM cycles. The default value of this option for ST-SWHAM is zero, which means performing the global jump in the ST-SWHAM analysis. The value larger than zero means performing that many times local jumps per cycle in the ST-SWHAM analysis.

2.1.9 -s print_list_of_states

"print_list_of_states" is a list of \(\lambda\)-state indexes. 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 index of \(\lambda\)-state starts from one, not zero. When the data are analyzed by RE-SWHAM (see option "-g"), the properties of the observation (see option "-p") sampled at those states listed in "print_list_of_states" will be printed out every RE cycle. If the data are analyzed by ST-SWHAM (see option "-g"), the free energy estimates of those states listed in "print_list_of_states" will be printed out.

2.1.10 -p print_list_of_properties

"print_list_of_properties" is a list of properties indexes. This option is only meaningful for RE-SWHAM analysis. During the RE-SWHAM analysis, the properties listed in "print_list_of_properties" of the observation sampled at those states listed in "print_list_of_states" (see option "-s") will be printed out every RE cycle. Note the index starts from one, not zero. If "print_list_of_properties" contains one single value zero (-p 0), the index of the observation will be printed out.

2.1.11 -g free_energy_print_frequency

Number of ST cycles between printing out free energy estimates during the ST-SWHAM. If this number is zero, the data will be analyzed by RE-SWHAM. If this number is position, the data will be analyzed by ST-SWHAM, and the free energy estimates of those states listed in "print_list_of_states" (see option "-s") will be printed out.

2.1.12 -k -m

These two options are used to reduce the zeros for the input of option "-q", "-n" and "-g" (not "-x"). If the "-k" switch is turned on, the input numbers of option "-q", "-n" and "-g" are in unit of one thousand. If the "-m" switch is turned on, the input numbers of option "-q", "-n" and "-g" are in unit of one million. If both are used, the input numbers of those options are in unit of one billion.

2.1.13 -w

If this switch is turned on, ST-SWHAM estimates the density of states of each observation by using the second equation of the UWHAM equation array. At the end of the ST-SWHAM analysis, the weight of each observation at the \(\lambda\)-state which it was observed will be printed out in the "weights.data" file.

Author: Bin Zhang

Created: 2018-05-02 Wed 17:40

Validate