Action: DRR
| Module | drr |
|---|---|
| Description | Usage |
| Used to performed extended-system adaptive biasing force (eABF) |   |
Details and examples
Used to performed extended-system adaptive biasing force (eABF)
This method was introduced in the first paper cited below. It is used on one or more collective variables. This method is also called dynamic reference restraining(DRR) as in the second paper cited below. A detailed description of this module can be found in the third paper cited below.
For each collective variable , a fictitious variable is attached through a spring. The fictitious variable undergoes overdamped Langevin dynamics just like EXTENDED_LAGRANGIAN. The ABF algorithm applies bias force on . The bias force acts on is the negative average spring force on , which enhances the sampling of .
If spring force constant k is large enough, then synchronizes with . The naive(ABF) estimator is just the negative average spring force of .
The naive(ABF) estimator is biased. There are unbiased estimators such as CZAR(Corrected z-averaged restraint) discussed in the fourth paper cited below and UI(Umbrella Integration). The CZAR estimates the gradients as:
The UI estimates the gradients as:
The code performing UI(colvar_UIestimator.h) is contributed by Haohao Fu (see fifth paper cited below). It may be slow. I only change the Boltzmann constant and output precision in it. For new version and issues, please see: https://github.com/fhh2626/colvars
After running eABF/DRR, the drr_tool utility can be used to extract the gradients and counts files from .drrstate. Naive(ABF) estimator's result is in .abf.grad and .abf.count files and CZAR estimator's result is in .czar.grad and .czar.count files. The additional .zcount and .zgrad files contain the number of samples of , and the negative of -averaged spring forces, respectively, which are mainly for inspecting and debugging purpose. To get PMF, the abf_integrate(https://github.com/Colvars/colvars/tree/master/colvartools) is useful for numerically integrating the .czar.grad file.
Examples
The following input tells plumed to perform a eABF/DRR simulation on two torsional angles.
Click on the labels of the actions for more information on what each action computes
phi: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=5,7,9,15 psi: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=7,9,15,17 DRRUsed to performed extended-system adaptive biasing force (eABF) This action has hidden defaults. More details ... LABELa label for the action so that its output can be referenced in the input to other actions=eabf ARGthe labels of the scalars on which the bias will act=phi,psi FULLSAMPLES number of samples in a bin prior to application of the ABF=500 GRID_MINthe lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified)=-pi,-pi GRID_MAXthe upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified)=pi,pi GRID_BINthe number of bins for the grid=180,180 FRICTION add a friction to the variable, similar to extended Langevin Damping in Colvars=8.0,8.0 TAU specifies relaxation time on each of variables are, similar to extended Time Constant in Colvars=0.5,0.5 OUTPUTFREQwrite results to a file every N steps=50000 HISTORYFREQsave history to a file every N steps=500000 ... DRR
# monitor the two variables, their fictitious variables and applied forces. PRINTPrint quantities to a file. More details STRIDE the frequency with which the quantities of interest should be output=10 ARGthe labels of the values that you would like to print to the file=phi,psi,eabf.phi_fict,eabf.psi_fict,eabf.phi_biasforce,eabf.psi_biasforce FILEthe name of the file on which to output these quantities=COLVAR
The following input tells plumed to perform a eABF/DRR simulation on the distance of atom 10 and 92. The distance is restraint by LOWER_WALLS and UPPER_WALLS.
Click on the labels of the actions for more information on what each action computes
dist1: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=10,92 eabf_winall: DRRUsed to performed extended-system adaptive biasing force (eABF) This action has hidden defaults. More details ARGthe labels of the scalars on which the bias will act=dist1 FULLSAMPLES number of samples in a bin prior to application of the ABF=2000 GRID_MINthe lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified)=1.20 GRID_MAXthe upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified)=3.20 GRID_BINthe number of bins for the grid=200 FRICTION add a friction to the variable, similar to extended Langevin Damping in Colvars=8.0 TAU specifies relaxation time on each of variables are, similar to extended Time Constant in Colvars=0.5 OUTPUTFREQwrite results to a file every N steps=5000 HISTORYFREQsave history to a file every N steps=500000 uwall: UPPER_WALLSDefines a wall for the value of one or more collective variables, More details ARGthe arguments on which the bias is acting=eabf_winall.dist1_fict ATthe positions of the wall=3.2 KAPPAthe force constant for the wall=418.4 lwall: LOWER_WALLSDefines a wall for the value of one or more collective variables, More details ARGthe arguments on which the bias is acting=eabf_winall.dist1_fict ATthe positions of the wall=1.2 KAPPAthe force constant for the wall=418.4 PRINTPrint quantities to a file. More details STRIDE the frequency with which the quantities of interest should be output=10 ARGthe labels of the values that you would like to print to the file=dist1,eabf_winall.dist1_fict,eabf_winall.dist1_biasforce FILEthe name of the file on which to output these quantities=COLVAR
It's also possible to run extended generalized adaptive biasing force (egABF) described in the sixth paper cited below. An egABF example:
Click on the labels of the actions for more information on what each action computes
phi: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=5,7,9,15 psi: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=7,9,15,17 DRRUsed to performed extended-system adaptive biasing force (eABF) This action has hidden defaults. More details ... LABELa label for the action so that its output can be referenced in the input to other actions=gabf_phi ARGthe labels of the scalars on which the bias will act=phi FULLSAMPLES number of samples in a bin prior to application of the ABF=500 GRID_MINthe lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified)=-pi GRID_MAXthe upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified)=pi GRID_BINthe number of bins for the grid=180 FRICTION add a friction to the variable, similar to extended Langevin Damping in Colvars=8.0 TAU specifies relaxation time on each of variables are, similar to extended Time Constant in Colvars=0.5 OUTPUTFREQwrite results to a file every N steps=50000 HISTORYFREQsave history to a file every N steps=500000 ... DRR
DRRUsed to performed extended-system adaptive biasing force (eABF) This action has hidden defaults. More details ... LABELa label for the action so that its output can be referenced in the input to other actions=gabf_psi ARGthe labels of the scalars on which the bias will act=psi FULLSAMPLES number of samples in a bin prior to application of the ABF=500 GRID_MINthe lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified)=-pi GRID_MAXthe upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified)=pi GRID_BINthe number of bins for the grid=180 FRICTION add a friction to the variable, similar to extended Langevin Damping in Colvars=8.0 TAU specifies relaxation time on each of variables are, similar to extended Time Constant in Colvars=0.5 OUTPUTFREQwrite results to a file every N steps=50000 HISTORYFREQsave history to a file every N steps=500000 ... DRR
DRRUsed to performed extended-system adaptive biasing force (eABF) This action has hidden defaults. More details ... LABELa label for the action so that its output can be referenced in the input to other actions=gabf_2d ARGthe labels of the scalars on which the bias will act=phi,psi EXTERNAL_FORCEuse forces from other action instead of internal spring force, this disable the extended system!=gabf_phi.phi_springforce,gabf_psi.psi_springforce EXTERNAL_FICTposition of external fictitious particles, useful for UIESTIMATOR=gabf_phi.phi_fictNoPBC,gabf_psi.psi_fictNoPBC GRID_MINthe lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified)=-pi,-pi GRID_MAXthe upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified)=pi,pi GRID_BINthe number of bins for the grid=180,180 NOBIAS DO NOT apply bias forces OUTPUTFREQwrite results to a file every N steps=50000 HISTORYFREQsave history to a file every N steps=500000 ... DRR
PRINTPrint quantities to a file. More details STRIDE the frequency with which the quantities of interest should be output=10 ARGthe labels of the values that you would like to print to the file=phi,psi FILEthe name of the file on which to output these quantities=COLVAR
Input
The arguments that serve as the input for this action are specified using one or more of the keywords in the following table.
| Keyword | Type | Description |
|---|---|---|
| ARG | scalar | the labels of the scalars on which the bias will act |
Output components
This action calculates the values in the following table. These values can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the value required from the list below.
| Name | Type | Description |
|---|---|---|
| bias | scalar | the instantaneous value of the bias potential |
| _fict | scalar | one or multiple instances of this quantity can be referenced elsewhere in the input file |
| _vfict | scalar | one or multiple instances of this quantity can be referenced elsewhere in the input file |
| _biasforce | scalar | The bias force from eABF/DRR of the fictitious particle |
| _springforce | scalar | Spring force between real CVs and extended CVs |
| _fictNoPBC | scalar | the positions of fictitious particles (without PBC) |
Full list of keywords
The following table describes the keywords and options that can be used with this action
| Keyword | Type | Default | Description |
|---|---|---|---|
| ARG | input | none | the labels of the scalars on which the bias will act |
| TAU | compulsory | 0.5 | specifies relaxation time on each of variables are, similar to extended Time Constant in Colvars |
| FRICTION | compulsory | 8.0 | add a friction to the variable, similar to extended Langevin Damping in Colvars |
| GRID_MIN | compulsory | none | the lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified) |
| GRID_MAX | compulsory | none | the upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified) |
| REFLECTINGWALL | compulsory | 0 | whether add reflecting walls for each CV at GRID_MIN and GRID_MAX |
| FULLSAMPLES | compulsory | 500 | number of samples in a bin prior to application of the ABF |
| MAXFACTOR | compulsory | 1.0 | maximum scaling factor of biasing force |
| OUTPUTFREQ | compulsory | none | write results to a file every N steps |
| NUMERICAL_DERIVATIVESThis keyword do not have examples | optional | false | calculate the derivatives for these quantities numerically |
| KAPPAThis keyword do not have examples | optional | not used | specifies that the restraint is harmonic and what the values of the force constants on each of the variables are (default to k_BT/(GRID_SPACING)^2) |
| GRID_BIN | optional | not used | the number of bins for the grid |
| GRID_SPACINGThis keyword do not have examples | optional | not used | the approximate grid spacing (to be used as an alternative or together with GRID_BIN) |
| ZGRID_MINThis keyword do not have examples | optional | not used | the lower bounds for the grid (ZGRID_BIN or ZGRID_SPACING should be specified) |
| ZGRID_MAXThis keyword do not have examples | optional | not used | the upper bounds for the grid (ZGRID_BIN or ZGRID_SPACING should be specified) |
| ZGRID_BINThis keyword do not have examples | optional | not used | the number of bins for the grid |
| ZGRID_SPACINGThis keyword do not have examples | optional | not used | the approximate grid spacing (to be used as an alternative or together with ZGRID_BIN) |
| EXTERNAL_FORCE | optional | not used | use forces from other action instead of internal spring force, this disable the extended system! |
| EXTERNAL_FICT | optional | not used | position of external fictitious particles, useful for UIESTIMATOR |
| HISTORYFREQ | optional | not used | save history to a file every N steps |
| NOCZARThis keyword do not have examples | optional | false | disable the CZAR estimator |
| UIThis keyword do not have examples | optional | false | enable the umbrella integration estimator |
| UIRESTARTPREFIXThis keyword do not have examples | optional | not used | specify the restart files for umbrella integration |
| OUTPUTPREFIXThis keyword do not have examples | optional | not used | specify the output prefix (default to the label name) |
| TEMPThis keyword do not have examples | optional | not used | the system temperature - needed when FRICTION is present |
| EXTTEMPThis keyword do not have examples | optional | not used | the temperature of extended variables (default to system temperature) |
| DRR_RFILEThis keyword do not have examples | optional | not used | specifies the restart file ( |
| NOBIAS | optional | false | DO NOT apply bias forces |
| TEXTOUTPUTThis keyword do not have examples | optional | false | use text output for grad and count files instead of boost::serialization binary output |
| MERGEHISTORYFILESThis keyword do not have examples | optional | false | output all historic results to a single file rather than multiple |
| FMTThis keyword do not have examples | optional | not used | specify format for outfiles files (useful for decrease the number of digits in regtests) |
References
More information about how this action can be used is available in the following articles:
- T. Lelièvre, M. Rousset, G. Stoltz, Computation of free energy profiles with parallel adaptive dynamics. The Journal of Chemical Physics. 126 (2007)
- L. Zheng, W. Yang, Practically Efficient and Robust Free Energy Calculations: Double-Integration Orthogonal Space Tempering. Journal of Chemical Theory and Computation. 8, 810–823 (2012)
- H. Chen, H. Fu, X. Shao, C. Chipot, W. Cai, ELF: An Extended-Lagrangian Free Energy Calculation Module for Multiple Molecular Dynamics Engines. Journal of Chemical Information and Modeling. 58, 1315–1318 (2018)
- A. Lesage, T. Lelièvre, G. Stoltz, J. Hénin, Smoothed Biasing Forces Yield Unbiased Free Energies with the Extended-System Adaptive Biasing Force Method. The Journal of Physical Chemistry B. 121, 3676–3685 (2016)
- H. Fu, X. Shao, C. Chipot, W. Cai, Extended Adaptive Biasing Force Algorithm. An On-the-Fly Implementation for Accurate Free-Energy Calculations. Journal of Chemical Theory and Computation. 12, 3506–3513 (2016)
- T. Zhao, H. Fu, T. Lelièvre, X. Shao, C. Chipot, W. Cai, The Extended Generalized Adaptive Biasing Force Algorithm for Multidimensional Free-Energy Calculations. Journal of Chemical Theory and Computation. 13, 1566–1576 (2017)