PMFLib Wiki - User contributions [en]

STM:Collective variables

2016-04-19T13:58:07Z

Xstepan3:

Navigation: [[Documentation]] / [[Methods]] / [[String Method]] / [[STM:Collective variables]]
----
__NOEDITSECTION__ __NOTOC__
Each collective variable used in the string method simulation is provided in a separate section [CV]. All these sections are included either in the special group if the collective variables are provided in the main control file or in the {MAIN} group of separate file. The name of the group or the file name is controlled be the fstmdef option provided in the [[General setup|[file]]] section.

==[CV]==
{| style="width: 100%;"
| style="width: 10em;" | '''Key'''
| style="width: 10em;" | '''Default value'''
| style="width: 5em;" | '''Type'''
| '''Description'''
|- style="vertical-align: top; background-color: #f6f6f6;"
| '''name'''
|
| [[Control key types|string]]
| The name of collective variable from the list of general collective variables. For details, see: [[ Collective Variables]]. The CV cannot be a member of [[managed path]].
|- style="vertical-align: top;"
| '''force_constant'''
|
| [[Control key types|real]]
| The force constant that will be used to fix the collective variable.
|}
''Keys in bold are mandatory.''

'''NOTE:''' Collective variables must be provided in the same order in which they are defined on the string server!

2016-04-19T11:44:16Z

Xstepan3:

Navigation: [[Documentation]] / [[Methods]] / [[Restrained Dynamics]] / [[RST:Utilities]] / [[rst-wham]]
----
{{RSTUtils}}
'''Name'''

rst-wham

'''Synopsis'''

wham [P|Ppi|Pval] hist_min hist_max num_bins tol temperature numpad metadatafile freefile [num_MC_trials randSeed] 

'''Description'''

These programs (wham and wham-2d) implement the [http://membrane.urmc.rochester.edu/sites/default/files/wham/doc.html Weighted Histogram Analysis Method of Kumar, et al ] ("Multidimensional free-energy calculations using the weighted histogram analysis method", J. Comput. Chem., 16:1339-1350, 1995). The code generally follows the notation used by Benoit Roux ("The calculation of the potential of mean force using computer simulations", Comput. Phys. Comm., 91:275-282, 1995). Consult these papers for the theoretical background and justification for the method.

'''Arguments'''

{| style="margin-left: 2em; width: 75%;"

|- style="vertical-align: top;"
| <nowiki>P|Ppi|Pval</nowiki> 
The first (optional) argument specifies the periodicity of the reaction coordinate. For a nonperiodic reaction coordinate (a distance, for example), it should be left out. "P" means that the reaction coordinate has a periodicity of 360, appropriate for angles. "Ppi" specifies a periodicity of 2*pi, appropriate for angles measured in radians. "Pval" specifies periodicty of some arbitrary amount, val, which should be an integer or floating point number. For example, "P180.0" would be appropriate for an angle with twofold symmetry.
|- style="vertical-align: top; background-color: #e6e6e6;"
| hist_min hist_max 
Specify the boundaries of the histogram. As a rule, all data points outside the range (hist_min, hist_max) are silently ignored. The only exception is that if an entire trajectory is outside the range, the program halts with an error message. The solution is to remove that file from the metadata file. hist_min and hist_max should be floating point numbers. 
|- style="vertical-align: top;"
| num_bins 
Specifies the number of bins in the histogram, and as a result the number of points in the final PMF. It should be an integer.
|- style="vertical-align: top; background-color: #e6e6e6;"
| tol 
tol is the convergence tolerance for the WHAM calculations. Specifically, the WHAM iteration is considered to be converged when no Fi value for any simulation window changes by more than tol on consecutive iterations. As the program runs, it prints the average change in the F values for the most recent iteration. Obviously, this number will be smaller than tol before the computation converges, because convergence is triggered by the largest change as opposed to the average.
|- style="vertical-align: top;"
| temperature 
temperature is a floating point number representing the temperature in Kelvin at which the weighted histogram calculation is performed. This does not have to be the temperature at which the simulations were performed (see below for discussion). 
|- style="vertical-align: top; background-color: #e6e6e6;"
| numpad 
numpad specifies the number of "padding" values that should be printed for periodic PMFs. This number should be set to 0 for aperiodic reaction coordinates. It doesn't actually affect the calculation in any way. Rather, it just alters the final printout of the free energy, to make plotting of periodic reaction coordinates simpler. This is more important for wham-2d than wham.
|- style="vertical-align: top;"
| metadatafile 
metadatafile specifies the name of the metadata file. The format of this file is described below.
|- style="vertical-align: top; background-color: #e6e6e6;"
| freefile 
freefile is the name used for the file containing the final PMF and probability distribution.
|- style="vertical-align: top;"
| num_MC_trials randSeed 
num_MC_trials and randSeed (Optional) are both related to the performance of Monte Carlo bootstrap error analysis. If these values are not supplied, error analysis is not performed. num_MC_trials should be an integer specifying the number of fake data sets which should be generated. randSeed is an integer which controls the random number seed - the value you pick should be irrelevant, but I let the user set it primarily for debugging purposes.
|}

'''File formats'''

{| style="margin-left: 2em; width: 95%;"
|- style="vertical-align: top; background-color: #e6e6e6;"
|metadata Each line of the metadata file should be blank, begin with a "#" (marking a comment), or have the following format:

::<code>/path/to/timeseries/file loc_win_min spring [correl time] [temperature]</code>

This first field is the name of one of the time series files (more on this in a moment). The second field, loc_win_min, is the location of the minimum of the biasing potential for this simulation, a floating point number. The third field, spring, is the spring constant for the biasing potential used in this simulation, assuming the biasing potential is of the format

::<math> V= \frac{1}{2}k (x-x_0)^2 </math>

Many simulation packages, including TINKER, AMBER, and CHARMM, do not include the [1/2] when they specify spring constants for their restraint terms. This is a common source of error (I'd love to change my code to match the other packages' behavior, but then experienced users who don't read the manual would get messed up). Also, the units for the spring constant must match those for the time series. So, if your time series is a distance recorded in Ångstroms, the spring constant must be in kcal/mol-Å2. AMBER users should take care when using angular restraints: the specification and output of angles is in degrees, but AMBER's spring constants use kcal/mol-rad^2.

The fourth argument ("correl time") specifies the decorrelation time for your time series, in units of time steps. It is only used when generating fake data sets for Monte Carlo bootstrap error analysis, where it modulates the number of points per fake data set. This argument is optional, and is ignored if you don't do error analysis. If you're doing multiple temperatures but not bootstrapping, set it to any integer value as a placeholder, and it'll be ignored. See section for more discussion about how to do bootstrapping.

Finally, the last (optional) field is the temperature for this simulation. If not supplied, the temperature specified on the command line is used. In the present version of the code, you must either leave the temperature unspecified for all simulations or specify it for all simulations.

The time series files must follow one of two formats, depending on whether the temperature was specified in the metadata file. If no temperature was specified, the file should contain two columns, where the first is the time (which isn't actually used), and the second is the position of the system along the reaction coordinate. Both numbers should be in floating point format. Lines beginning with "#" are ignored as comments. Additional columns of data are ignored.
If the simulation temperature is specified, there must be a third column of data, containing the system's potential energy at that time point. It should be a floating point value.


|- style="vertical-align: top;"
|freefile 
The first line of the output file contains echoes command line. The next line or two contain comments describing the periodicity used and the number of simulation windows present. While the calculation is running, it will print out lines that look like the following:

#Iteration 10: 0.106019
#Iteration 20: 0.062269
#Iteration 30: 0.039890
#Iteration 40: 0.027003

This specifies the current iteration number, and the average change in the F values for the current iteration. This number is not used for deciding when the calculation has converged; rather, the maximum change, as opposed to the average, is used.
Every 100 iterations, the current version of the PMF is dumped into the output file. These lines look like

-178.000000 0.014212 4909.138943
-174.000000 0.062631 4525.390035
-170.000000 0.227076 3432.434076
-166.000000 0.494262 2190.487110
-162.000000 0.817734 1271.708620

The first column is the value of the reaction coordinate, the second is the value of the PMF, and the third is the unnormalized probability distribution.
Once the calculation has converged, wham will produce output resembling

# Dumping simulation biases, in the metadata file order
# Window F (free energy units)
# 0 0.000004
# 1 -4.166136
# 2 -3.241052
# 3 -4.475215
# 4 -6.324340
# 5 -7.128731

These are the final F values from the wham calculation, and can be used for computing weighted averages for properties other than the free energy.
You may have noticed that all of the lines except the free energies are preceded by "#". This allows you to check convergence of your wham calculation by simply plotting the output file in gnuplot. If the free energy curves have stopped changing, your tolerance is small enough.
If you specified a nonzero number of Monte Carlo bootstrap error analysis trials, you will see lines that resemble

#MC trial 0: 990 iterations
#MC trial 1: 973 iterations
#MC trial 2: 970 iterations
#MC trial 3: 981 iterations
#MC trial 4: 984 iterations

at the end of the file.
The free energy data file is written when the calculation converges, and resembles:

#Coor Free +/- Prob +/-
-178.000000 0.014386 0.000098 0.106389 0.000017
-174.000000 0.068560 0.000151 0.097128 0.000025
-170.000000 0.250825 0.000350 0.071496 0.000042
-166.000000 0.523786 0.000294 0.045186 0.000022

The first column is the value of the reaction coordinate, the second is the free energy. The third is the statistical uncertainty of the free energy (which is only meaningful if you performed Monte Carlo bootstrapping). The fourth and fifth columns are the probability and it's associated statistical uncertainty. Again, the latter is only meaningful if bootstrapping is performed. See section for further discussion of error estimation.

|}

Rst-wham

2016-04-19T11:43:29Z

Xstepan3:

Rst-wham

2016-04-19T11:41:05Z

Xstepan3:

Navigation: [[Documentation]] / [[Methods]] / [[Restrained Dynamics]] / [[RST:Utilities]] / [[rst-wham]]
----
{{RSTUtils}}
'''Name'''

rst-wham

'''Synopsis'''

wham [P|Ppi|Pval] hist_min hist_max num_bins tol temperature numpad metadatafile freefile [num_MC_trials randSeed] 

'''Description'''

These programs (wham and wham-2d) implement the [http://membrane.urmc.rochester.edu/sites/default/files/wham/doc.html Weighted Histogram Analysis Method of Kumar, et al ] ("Multidimensional free-energy calculations using the weighted histogram analysis method", J. Comput. Chem., 16:1339-1350, 1995). The code generally follows the notation used by Benoit Roux ("The calculation of the potential of mean force using computer simulations", Comput. Phys. Comm., 91:275-282, 1995). Consult these papers for the theoretical background and justification for the method.

'''Arguments'''

{| style="margin-left: 2em; width: 75%;"

|- style="vertical-align: top;"
| <nowiki>P|Ppi|Pval</nowiki> 
The first (optional) argument specifies the periodicity of the reaction coordinate. For a nonperiodic reaction coordinate (a distance, for example), it should be left out. "P" means that the reaction coordinate has a periodicity of 360, appropriate for angles. "Ppi" specifies a periodicity of 2*pi, appropriate for angles measured in radians. "Pval" specifies periodicty of some arbitrary amount, val, which should be an integer or floating point number. For example, "P180.0" would be appropriate for an angle with twofold symmetry.
|- style="vertical-align: top; background-color: #e6e6e6;"
| hist_min hist_max 
Specify the boundaries of the histogram. As a rule, all data points outside the range (hist_min, hist_max) are silently ignored. The only exception is that if an entire trajectory is outside the range, the program halts with an error message. The solution is to remove that file from the metadata file. hist_min and hist_max should be floating point numbers. 
|- style="vertical-align: top;"
| num_bins 
Specifies the number of bins in the histogram, and as a result the number of points in the final PMF. It should be an integer.
|- style="vertical-align: top; background-color: #e6e6e6;"
| tol 
tol is the convergence tolerance for the WHAM calculations. Specifically, the WHAM iteration is considered to be converged when no Fi value for any simulation window changes by more than tol on consecutive iterations. As the program runs, it prints the average change in the F values for the most recent iteration. Obviously, this number will be smaller than tol before the computation converges, because convergence is triggered by the largest change as opposed to the average.
|- style="vertical-align: top;"
| temperature 
temperature is a floating point number representing the temperature in Kelvin at which the weighted histogram calculation is performed. This does not have to be the temperature at which the simulations were performed (see below for discussion). 
|- style="vertical-align: top; background-color: #e6e6e6;"
| numpad 
numpad specifies the number of "padding" values that should be printed for periodic PMFs. This number should be set to 0 for aperiodic reaction coordinates. It doesn't actually affect the calculation in any way. Rather, it just alters the final printout of the free energy, to make plotting of periodic reaction coordinates simpler. This is more important for wham-2d than wham.
|- style="vertical-align: top;"
| metadatafile 
metadatafile specifies the name of the metadata file. The format of this file is described below.
|- style="vertical-align: top; background-color: #e6e6e6;"
| freefile 
freefile is the name used for the file containing the final PMF and probability distribution.
|- style="vertical-align: top;"
| num_MC_trials randSeed 
num_MC_trials and randSeed (Optional) are both related to the performance of Monte Carlo bootstrap error analysis. If these values are not supplied, error analysis is not performed. num_MC_trials should be an integer specifying the number of fake data sets which should be generated. randSeed is an integer which controls the random number seed - the value you pick should be irrelevant, but I let the user set it primarily for debugging purposes.
|}

'''File formats'''

{| style="margin-left: 2em; width: 95%;"
|- style="vertical-align: top; background-color: #e6e6e6;"
|metadata Each line of the metadata file should be blank, begin with a "#" (marking a comment), or have the following format:

::<code>/path/to/timeseries/file loc_win_min spring [correl time] [temperature]</code>

This first field is the name of one of the time series files (more on this in a moment). The second field, loc_win_min, is the location of the minimum of the biasing potential for this simulation, a floating point number. The third field, spring, is the spring constant for the biasing potential used in this simulation, assuming the biasing potential is of the format

::<math> V= \frac{1}{2}k (x-x_0)^2 </math>

Many simulation packages, including TINKER, AMBER, and CHARMM, do not include the [1/2] when they specify spring constants for their restraint terms. This is a common source of error (I'd love to change my code to match the other packages' behavior, but then experienced users who don't read the manual would get messed up). Also, the units for the spring constant must match those for the time series. So, if your time series is a distance recorded in Ångstroms, the spring constant must be in kcal/mol-Å2. AMBER users should take care when using angular restraints: the specification and output of angles is in degrees, but AMBER's spring constants use kcal/mol-rad^2.

The fourth argument ("correl time") specifies the decorrelation time for your time series, in units of time steps. It is only used when generating fake data sets for Monte Carlo bootstrap error analysis, where it modulates the number of points per fake data set. This argument is optional, and is ignored if you don't do error analysis. If you're doing multiple temperatures but not bootstrapping, set it to any integer value as a placeholder, and it'll be ignored. See section for more discussion about how to do bootstrapping.

Finally, the last (optional) field is the temperature for this simulation. If not supplied, the temperature specified on the command line is used. In the present version of the code, you must either leave the temperature unspecified for all simulations or specify it for all simulations.

The time series files must follow one of two formats, depending on whether the temperature was specified in the metadata file. If no temperature was specified, the file should contain two columns, where the first is the time (which isn't actually used), and the second is the position of the system along the reaction coordinate. Both numbers should be in floating point format. Lines beginning with "#" are ignored as comments. Additional columns of data are ignored.
If the simulation temperature is specified, there must be a third column of data, containing the system's potential energy at that time point. It should be a floating point value.


|- style="vertical-align: top;"
|freefile 
The first line of the output file contains echoes command line. The next line or two contain comments describing the periodicity used and the number of simulation windows present. While the calculation is running, it will print out lines that look like the following:

<code>#Iteration 10: 0.106019
#Iteration 20: 0.062269
#Iteration 30: 0.039890
#Iteration 40: 0.027003</code>

This specifies the current iteration number, and the average change in the F values for the current iteration. This number is not used for deciding when the calculation has converged; rather, the maximum change, as opposed to the average, is used.
Every 100 iterations, the current version of the PMF is dumped into the output file. These lines look like

-178.000000 0.014212 4909.138943
-174.000000 0.062631 4525.390035
-170.000000 0.227076 3432.434076
-166.000000 0.494262 2190.487110
-162.000000 0.817734 1271.708620

The first column is the value of the reaction coordinate, the second is the value of the PMF, and the third is the unnormalized probability distribution.
Once the calculation has converged, wham will produce output resembling

# Dumping simulation biases, in the metadata file order
# Window F (free energy units)
# 0 0.000004
# 1 -4.166136
# 2 -3.241052
# 3 -4.475215
# 4 -6.324340
# 5 -7.128731

These are the final F values from the wham calculation, and can be used for computing weighted averages for properties other than the free energy.
You may have noticed that all of the lines except the free energies are preceded by "#". This allows you to check convergence of your wham calculation by simply plotting the output file in gnuplot. If the free energy curves have stopped changing, your tolerance is small enough.
If you specified a nonzero number of Monte Carlo bootstrap error analysis trials, you will see lines that resemble

#MC trial 0: 990 iterations
#MC trial 1: 973 iterations
#MC trial 2: 970 iterations
#MC trial 3: 981 iterations
#MC trial 4: 984 iterations

at the end of the file.
The free energy data file is written when the calculation converges, and resembles:

#Coor Free +/- Prob +/-
-178.000000 0.014386 0.000098 0.106389 0.000017
-174.000000 0.068560 0.000151 0.097128 0.000025
-170.000000 0.250825 0.000350 0.071496 0.000042
-166.000000 0.523786 0.000294 0.045186 0.000022

The first column is the value of the reaction coordinate, the second is the free energy. The third is the statistical uncertainty of the free energy (which is only meaningful if you performed Monte Carlo bootstrapping). The fourth and fifth columns are the probability and it's associated statistical uncertainty. Again, the latter is only meaningful if bootstrapping is performed. See section for further discussion of error estimation.


|}

Abf-trajectory

2016-04-18T12:41:34Z

Xstepan3:

Navigation: [[Documentation]] / [[Methods]] / [[Adaptive Biasing Force Method]] / [[ABF:Utilities]] / [[abf-trajectory]]
----
{{ABFUtils}}
'''Name'''

abf-trajectory

'''Synopsis'''

abf-trajectory [OPTIONS] [--] trjname accuname 

'''Description'''

It extracts a single snapshot from the ABF accumulator trajectory.

'''Arguments'''

{| style="margin-left: 2em; width: 75%;"
|- style="vertical-align: top; background-color: #e6e6e6;"
| trjname 
Name of file containing the ABF accumulator trajectory. If the name is '-' then the trajectory is read from the standard input.
|- style="vertical-align: top;"
| accuname 
Name of file where a snapsphot (ABF accumulator) will be printed. If the name is '-' then the output will be written to the standard output.
|}

'''Options'''

{| style="margin-left: 2em; width: 95%;"
|- style="vertical-align: top; background-color: #e6e6e6;"
|-s, --snapshot NUMBER Index of extracted snapshot (counted from 1). (Default: 1)
|- style="vertical-align: top; "
|-v, --verbose Increase output verbosity.
|- style="vertical-align: top; background-color: #e6e6e6;"
|--version Output version information and exit.
|- style="vertical-align: top; "
|-h, --help Display this help and exit.
|}

Abf-samples

2016-04-18T12:40:06Z

Xstepan3:

Navigation: [[Documentation]] / [[Methods]] / [[Adaptive Biasing Force Method]] / [[ABF:Utilities]] / [[abf-samples]]
----
{{ABFUtils}}
'''Name'''

abf-samples

'''Synopsis'''

abf-samples [OPTIONS] [--] accuname sname 

'''Description'''

It prints number of samples accumulated during the ABF calculation.

'''Arguments'''

{| style="margin-left: 2em; width: 75%;"
|- style="vertical-align: top; background-color: #e6e6e6;"
| accuname 
Name of file containing the ABF accumulator. If the name is '-' then the accumulator is read from the standard input.
|- style="vertical-align: top;"
| sname 
Name of file where the info about samples will be printed. If the name is '-' then the output will be written to the standard output.
|}

'''Options'''

{| style="margin-left: 2em; width: 95%;"
|- style="vertical-align: top; background-color: #e6e6e6;"
|-l, --limit NUMBER Only bins containing more samples than NUMBER are considered as properly sampled. (Default: 0)
|- style="vertical-align: top; "
|--nognuplot Do not print delimiters between records.
|- style="vertical-align: top; background-color: #e6e6e6;"
|--fx FORMAT Output FORMAT, which will be used to print values of collective variables. (Default: %15.7e)
|- style="vertical-align: top; "
|--fe FORMAT Output FORMAT, which will be used to print samples. (Default: %d)
|- style="vertical-align: top; background-color: #e6e6e6;"
|-v, --verbose Increase output verbosity.
|- style="vertical-align: top; "
|--version Output version information and exit.
|- style="vertical-align: top; background-color: #e6e6e6;"
|-h, --help Display this help and exit.
|}

Xstepan3: Created page with "Navigation: Documentation / Methods / Restrained Dynamics / RST:Utilities / rst-wham ---- {{RSTUtils}} '''Name''' rst-wham '''Synopsis''' <span style="c..."

Rst-samples

2016-04-11T13:31:45Z

Xstepan3:

Navigation: [[Documentation]] / [[Methods]] / [[Restrained Dynamics]] / [[RST:Utilities]] / [[rst-samples]]
----
{{RSTUtils}}
'''Name'''

rst-samples

'''Synopsis'''

rst-samples [OPTIONS] [--] accuname sname 

'''Description'''

It prints the number of samples accumulated during RST calculation.

'''Arguments'''

{| style="margin-left: 2em; width: 75%;"
|- style="vertical-align: top; background-color: #e6e6e6;"
| accuname 
File name of the RST histogram file. If the name is '-' then the accumulator is read from the standard input.
|- style="vertical-align: top;"
| sname 
Name of file where the info about samples will be printed. If the name is '-' then the output will be written to the standard output.
|}

'''Options'''

{| style="margin-left: 2em; width: 95%;"
|- style="vertical-align: top; background-color: #e6e6e6;"
|-l, --limit LIMIT only bins with the number of samples grater than or equal to LIMIT will be printed (Default: 0)
|- style="vertical-align: top; "
|--nognuplot do not print delimiters between records
|- style="vertical-align: top; background-color: #e6e6e6;"
|--fx FORMAT output FORMAT of coordinate values (Default: %15.7le)
|- style="vertical-align: top; "
|--fe FORMAT output FORMAT of samples (Default: %d)
|- style="vertical-align: top; background-color: #e6e6e6;"
|-v, --verbose increase output verbosity
|- style="vertical-align: top; "
|--version output version information and exit
|- style="vertical-align: top; background-color: #e6e6e6;"
|-h, --help display this help and exit
|}