DRR

	This is part of the drr module
	It is only available if you configure PLUMED with ./configure –enable-modules=drr . Furthermore, this feature is still being developed so take care when using it and report any problems on the mailing list.

Used to performed extended-system adaptive biasing force(eABF)

This method was introduced in [67]. It is used on one or more collective variables. This method is also called dynamic reference restraining(DRR) [119] . A detailed description of this module can be found at [32] .

For each collective variable \(\xi_i\), a fictitious variable \(\lambda_i\) is attached through a spring. The fictitious variable \(\lambda_i\) undergoes overdamped Langevin dynamics just like EXTENDED_LAGRANGIAN. The ABF algorithm applies bias force on \(\lambda_i\). The bias force acts on \(\lambda_i\) is the negative average spring force on \(\lambda_i\), which enhances the sampling of \(\lambda_i\).

\[ F_{bias}(\lambda_i)=k(\lambda_i-\langle\xi_i\rangle_{\lambda_i}) \]

If spring force constant k is large enough, then \(\xi_i\) synchronizes with \(\lambda_i\). The naive(ABF) estimator is just the negative average spring force of \(\lambda_i\).

The naive(ABF) estimator is biased. There are unbiased estimators such as CZAR(Corrected z-averaged restraint) [68] and UI(Umbrella Integration). The CZAR estimates the gradients as:

\[ \frac{\partial{A}}{\partial{\xi_i}}\left({\xi}\right)=-\frac{1}{\beta}\frac{\partial\ln\tilde{\rho}\left(\xi\right)}{\partial{\xi_i}}+k\left(\langle\lambda_i\rangle_\xi-\xi_i\right) \]

The UI estimates the gradients as:

\[ A'(\xi^*)=\frac{{\sum_\lambda}N\left(\xi^*,\lambda\right)\left[\frac{\xi^*-\langle\xi\rangle_\lambda}{\beta\sigma_\lambda^2}-k(\xi^*-\lambda)\right]}{{\sum_\lambda}N\left(\xi^*,\lambda\right)} \]

The code performing UI(colvar_UIestimator.h) is contributed by Haohao Fu [41] . 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 \(\boldsymbol{\xi}\), and the negative of \(\boldsymbol{\xi}\)-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: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=5,7,9,15 The TORSION action with label phi calculates a single scalar value
psi: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=7,9,15,17 The TORSION action with label psi calculates a single scalar value
eabf: DRR ...
   
   
ARG
compulsory keyword 
the labels of the scalars on which the bias will act 
=phi,psi 
   
FULLSAMPLES
compulsory keyword ( default=500 )
number of samples in a bin prior to application of the ABF 
=500 
   
GRID_MIN
compulsory keyword 
the lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=-pi,-pi 
   
GRID_MAX
compulsory keyword 
the upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=pi,pi 
   
GRID_BIN
the number of bins for the grid 
=180,180 
   
FRICTION
compulsory keyword ( default=8.0 )
add a friction to the variable, similar to extended Langevin Damping in Colvars 
=8.0,8.0 
   
TAU
compulsory keyword ( default=0.5 )
specifies relaxation time on each of variables are, similar to extended Time Constant
in Colvars 
=0.5,0.5 
   
OUTPUTFREQ
compulsory keyword 
write results to a file every N steps 
=50000 
   
HISTORYFREQ
save history to a file every N steps 
=500000 
...The DRR action with label eabf calculates the following quantities:

 Quantity   
 Description  
eabf.bias
the instantaneous value of the bias potential
eabf.phi_fict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is possible to add forces on these variable. This particular component measures this quantity for the input CV named phi
eabf.phi_vfict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is NOT possible to add forces on these variable. This particular component measures this quantity for the input CV named phi
eabf.phi_biasforce
The bias force from eABF/DRR of the fictitious particle. This particular component measures this quantity for the input CV named phi
eabf.phi_springforce
Spring force between real CVs and extended CVs This particular component measures this quantity for the input CV named phi
eabf.phi_fictNoPBC
the positions of fictitious particles (without PBC). This particular component measures this quantity for the input CV named phi
eabf.psi_fict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is possible to add forces on these variable. This particular component measures this quantity for the input CV named psi
eabf.psi_vfict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is NOT possible to add forces on these variable. This particular component measures this quantity for the input CV named psi
eabf.psi_biasforce
The bias force from eABF/DRR of the fictitious particle. This particular component measures this quantity for the input CV named psi
eabf.psi_springforce
Spring force between real CVs and extended CVs This particular component measures this quantity for the input CV named psi
eabf.psi_fictNoPBC
the positions of fictitious particles (without PBC). This particular component measures this quantity for the input CV named psi


# monitor the two variables, their fictitious variables and applied forces.
PRINT 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=10 
ARG
compulsory keyword 
the 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 
FILE
the name of the file on which to output these quantities 
=COLVAR The PRINT action with label 

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

contract shortcuts

dist1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,92 The DISTANCE action with label dist1 calculates a single scalar value
eabf_winall: DRR 
ARG
compulsory keyword 
the labels of the scalars on which the bias will act 
=dist1 
FULLSAMPLES
compulsory keyword ( default=500 )
number of samples in a bin prior to application of the ABF 
=2000 
GRID_MIN
compulsory keyword 
the lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=1.20 
GRID_MAX
compulsory keyword 
the upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=3.20 
GRID_BIN
the number of bins for the grid 
=200 
FRICTION
compulsory keyword ( default=8.0 )
add a friction to the variable, similar to extended Langevin Damping in Colvars 
=8.0 
TAU
compulsory keyword ( default=0.5 )
specifies relaxation time on each of variables are, similar to extended Time Constant
in Colvars 
=0.5 
OUTPUTFREQ
compulsory keyword 
write results to a file every N steps 
=5000 
HISTORYFREQ
save history to a file every N steps 
=500000 The DRR action with label eabf_winall calculates the following quantities:

 Quantity   
 Description  
eabf_winall.bias
the instantaneous value of the bias potential
eabf_winall.dist1_fict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is possible to add forces on these variable. This particular component measures this quantity for the input CV named dist1
eabf_winall.dist1_vfict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is NOT possible to add forces on these variable. This particular component measures this quantity for the input CV named dist1
eabf_winall.dist1_biasforce
The bias force from eABF/DRR of the fictitious particle. This particular component measures this quantity for the input CV named dist1
eabf_winall.dist1_springforce
Spring force between real CVs and extended CVs This particular component measures this quantity for the input CV named dist1
eabf_winall.dist1_fictNoPBC
the positions of fictitious particles (without PBC). This particular component measures this quantity for the input CV named dist1


uwall: UPPER_WALLS 
ARG
the arguments on which the bias is acting. 
=eabf_winall.dist1_fict 
AT
compulsory keyword 
the positions of the wall. 
=3.2 
KAPPA
compulsory keyword 
the force constant for the wall. 
=418.4 The UPPER_WALLS action with label uwall calculates the following quantities:

 Quantity   
 Description  
uwall.bias
the instantaneous value of the bias potential
uwall.force2
the instantaneous value of the squared force due to this bias potential


lwall: LOWER_WALLS 
ARG
the arguments on which the bias is acting. 
=eabf_winall.dist1_fict 
AT
compulsory keyword 
the positions of the wall. 
=1.2 
KAPPA
compulsory keyword 
the force constant for the wall. 
=418.4 The LOWER_WALLS action with label lwall calculates the following quantities:

 Quantity   
 Description  
lwall.bias
the instantaneous value of the bias potential
lwall.force2
the instantaneous value of the squared force due to this bias potential


PRINT 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=10 
ARG
compulsory keyword 
the labels of the values that you would like to print to the file 
=dist1,eabf_winall.dist1_fict,eabf_winall.dist1_biasforce 
FILE
the name of the file on which to output these quantities 
=COLVAR The PRINT action with label 

dist1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,92 The DISTANCE action with label dist1 calculates a single scalar value
eabf_winall: DRR 
ARG
compulsory keyword 
the labels of the scalars on which the bias will act 
=dist1 
FULLSAMPLES
compulsory keyword ( default=500 )
number of samples in a bin prior to application of the ABF 
=2000 
GRID_MIN
compulsory keyword 
the lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=1.20 
GRID_MAX
compulsory keyword 
the upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=3.20 
GRID_BIN
the number of bins for the grid 
=200 
FRICTION
compulsory keyword ( default=8.0 )
add a friction to the variable, similar to extended Langevin Damping in Colvars 
=8.0 
TAU
compulsory keyword ( default=0.5 )
specifies relaxation time on each of variables are, similar to extended Time Constant
in Colvars 
=0.5 
OUTPUTFREQ
compulsory keyword 
write results to a file every N steps 
=5000 
HISTORYFREQ
save history to a file every N steps 
=500000 The DRR action with label eabf_winall calculates the following quantities:

 Quantity   
 Description  
eabf_winall.bias
the instantaneous value of the bias potential
eabf_winall.dist1_fict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is possible to add forces on these variable. This particular component measures this quantity for the input CV named dist1
eabf_winall.dist1_vfict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is NOT possible to add forces on these variable. This particular component measures this quantity for the input CV named dist1
eabf_winall.dist1_biasforce
The bias force from eABF/DRR of the fictitious particle. This particular component measures this quantity for the input CV named dist1
eabf_winall.dist1_springforce
Spring force between real CVs and extended CVs This particular component measures this quantity for the input CV named dist1
eabf_winall.dist1_fictNoPBC
the positions of fictitious particles (without PBC). This particular component measures this quantity for the input CV named dist1


PRINT 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=10 
ARG
compulsory keyword 
the labels of the values that you would like to print to the file 
=dist1,eabf_winall.dist1_fict,eabf_winall.dist1_biasforce 
FILE
the name of the file on which to output these quantities 
=COLVAR The PRINT action with label 

It's also possible to run extended generalized adaptive biasing force (egABF) described in [118] . An egABF example:

Click on the labels of the actions for more information on what each action computes

phi: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=5,7,9,15 The TORSION action with label phi calculates a single scalar value
psi: TORSION 
ATOMS
the four atoms involved in the torsional angle 
=7,9,15,17 The TORSION action with label psi calculates a single scalar value
gabf_phi: DRR ...
   
   
ARG
compulsory keyword 
the labels of the scalars on which the bias will act 
=phi 
   
FULLSAMPLES
compulsory keyword ( default=500 )
number of samples in a bin prior to application of the ABF 
=500 
   
GRID_MIN
compulsory keyword 
the lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=-pi 
   
GRID_MAX
compulsory keyword 
the upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=pi 
   
GRID_BIN
the number of bins for the grid 
=180 
   
FRICTION
compulsory keyword ( default=8.0 )
add a friction to the variable, similar to extended Langevin Damping in Colvars 
=8.0 
   
TAU
compulsory keyword ( default=0.5 )
specifies relaxation time on each of variables are, similar to extended Time Constant
in Colvars 
=0.5 
   
OUTPUTFREQ
compulsory keyword 
write results to a file every N steps 
=50000 
   
HISTORYFREQ
save history to a file every N steps 
=500000 
...The DRR action with label gabf_phi calculates the following quantities:

 Quantity   
 Description  
gabf_phi.bias
the instantaneous value of the bias potential
gabf_phi.phi_fict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is possible to add forces on these variable. This particular component measures this quantity for the input CV named phi
gabf_phi.phi_vfict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is NOT possible to add forces on these variable. This particular component measures this quantity for the input CV named phi
gabf_phi.phi_biasforce
The bias force from eABF/DRR of the fictitious particle. This particular component measures this quantity for the input CV named phi
gabf_phi.phi_springforce
Spring force between real CVs and extended CVs This particular component measures this quantity for the input CV named phi
gabf_phi.phi_fictNoPBC
the positions of fictitious particles (without PBC). This particular component measures this quantity for the input CV named phi


gabf_psi: DRR ...
   
   
ARG
compulsory keyword 
the labels of the scalars on which the bias will act 
=psi 
   
FULLSAMPLES
compulsory keyword ( default=500 )
number of samples in a bin prior to application of the ABF 
=500 
   
GRID_MIN
compulsory keyword 
the lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=-pi 
   
GRID_MAX
compulsory keyword 
the upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=pi 
   
GRID_BIN
the number of bins for the grid 
=180 
   
FRICTION
compulsory keyword ( default=8.0 )
add a friction to the variable, similar to extended Langevin Damping in Colvars 
=8.0 
   
TAU
compulsory keyword ( default=0.5 )
specifies relaxation time on each of variables are, similar to extended Time Constant
in Colvars 
=0.5 
   
OUTPUTFREQ
compulsory keyword 
write results to a file every N steps 
=50000 
   
HISTORYFREQ
save history to a file every N steps 
=500000 
...The DRR action with label gabf_psi calculates the following quantities:

 Quantity   
 Description  
gabf_psi.bias
the instantaneous value of the bias potential
gabf_psi.psi_fict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is possible to add forces on these variable. This particular component measures this quantity for the input CV named psi
gabf_psi.psi_vfict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is NOT possible to add forces on these variable. This particular component measures this quantity for the input CV named psi
gabf_psi.psi_biasforce
The bias force from eABF/DRR of the fictitious particle. This particular component measures this quantity for the input CV named psi
gabf_psi.psi_springforce
Spring force between real CVs and extended CVs This particular component measures this quantity for the input CV named psi
gabf_psi.psi_fictNoPBC
the positions of fictitious particles (without PBC). This particular component measures this quantity for the input CV named psi


gabf_2d: DRR ...
   
   
ARG
compulsory keyword 
the labels of the scalars on which the bias will act 
=phi,psi 
   
EXTERNAL_FORCE
use forces from other action instead of internal spring force, this disable the extended
system! 
=gabf_phi.phi_springforce,gabf_psi.psi_springforce 
   
EXTERNAL_FICT
position of external fictitious particles, useful for UIESTIMATOR 
=gabf_phi.phi_fictNoPBC,gabf_psi.psi_fictNoPBC 
   
GRID_MIN
compulsory keyword 
the lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=-pi,-pi 
   
GRID_MAX
compulsory keyword 
the upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified) 
=pi,pi 
   
GRID_BIN
the number of bins for the grid 
=180,180 
   
NOBIAS
( default=off ) DO NOT apply bias forces. 
 
   
OUTPUTFREQ
compulsory keyword 
write results to a file every N steps 
=50000 
   
HISTORYFREQ
save history to a file every N steps 
=500000 
...The DRR action with label gabf_2d calculates the following quantities:

 Quantity   
 Description  
gabf_2d.bias
the instantaneous value of the bias potential
gabf_2d.phi_fict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is possible to add forces on these variable. This particular component measures this quantity for the input CV named phi
gabf_2d.phi_vfict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is NOT possible to add forces on these variable. This particular component measures this quantity for the input CV named phi
gabf_2d.phi_biasforce
The bias force from eABF/DRR of the fictitious particle. This particular component measures this quantity for the input CV named phi
gabf_2d.phi_springforce
Spring force between real CVs and extended CVs This particular component measures this quantity for the input CV named phi
gabf_2d.phi_fictNoPBC
the positions of fictitious particles (without PBC). This particular component measures this quantity for the input CV named phi
gabf_2d.psi_fict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is possible to add forces on these variable. This particular component measures this quantity for the input CV named psi
gabf_2d.psi_vfict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is NOT possible to add forces on these variable. This particular component measures this quantity for the input CV named psi
gabf_2d.psi_biasforce
The bias force from eABF/DRR of the fictitious particle. This particular component measures this quantity for the input CV named psi
gabf_2d.psi_springforce
Spring force between real CVs and extended CVs This particular component measures this quantity for the input CV named psi
gabf_2d.psi_fictNoPBC
the positions of fictitious particles (without PBC). This particular component measures this quantity for the input CV named psi


PRINT 
STRIDE
compulsory keyword ( default=1 )
the frequency with which the quantities of interest should be output 
=10 
ARG
compulsory keyword 
the labels of the values that you would like to print to the file 
=phi,psi 
FILE
the name of the file on which to output these quantities 
=COLVAR The PRINT action with label 

Glossary of keywords and components

Description of components

By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the quantity required from the list below.

Quantity	Description
bias	the instantaneous value of the bias potential
_fict	one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is possible to add forces on these variable.
_vfict	one or multiple instances of this quantity can be referenced elsewhere in the input file. These quantities will named with the arguments of the bias followed by the character string _tilde. It is NOT possible to add forces on these variable.
_biasforce	The bias force from eABF/DRR of the fictitious particle.
_springforce	Spring force between real CVs and extended CVs
_fictNoPBC	the positions of fictitious particles (without PBC).

Compulsory keywords

ARG	the labels of the scalars on which the bias will act
TAU	( default=0.5 ) specifies relaxation time on each of variables are, similar to extended Time Constant in Colvars
FRICTION	( default=8.0 ) add a friction to the variable, similar to extended Langevin Damping in Colvars
GRID_MIN	the lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified)
GRID_MAX	the upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified)
REFLECTINGWALL	( default=0 ) whether add reflecting walls for each CV at GRID_MIN and GRID_MAX. Setting non-zero values will enable this feature
FULLSAMPLES	( default=500 ) number of samples in a bin prior to application of the ABF
MAXFACTOR	( default=1.0 ) maximum scaling factor of biasing force
OUTPUTFREQ	write results to a file every N steps

Options

NUMERICAL_DERIVATIVES	( default=off ) calculate the derivatives for these quantities numerically
NOCZAR	( default=off ) disable the CZAR estimator
UI	( default=off ) enable the umbrella integration estimator
NOBIAS	( default=off ) DO NOT apply bias forces.
TEXTOUTPUT	( default=off ) use text output for grad and count files instead of boost::serialization binary output
MERGEHISTORYFILES	( default=off ) output all historic results to a single file rather than multiple .drrstate files. This option is effective only when textOutput is on.
KAPPA	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	the number of bins for the grid
GRID_SPACING	the approximate grid spacing (to be used as an alternative or together with GRID_BIN)
ZGRID_MIN	the lower bounds for the grid (ZGRID_BIN or ZGRID_SPACING should be specified)
ZGRID_MAX	the upper bounds for the grid (ZGRID_BIN or ZGRID_SPACING should be specified)
ZGRID_BIN	the number of bins for the grid
ZGRID_SPACING	the approximate grid spacing (to be used as an alternative or together with ZGRID_BIN)
EXTERNAL_FORCE	use forces from other action instead of internal spring force, this disable the extended system!
EXTERNAL_FICT	position of external fictitious particles, useful for UIESTIMATOR
HISTORYFREQ	save history to a file every N steps
UIRESTARTPREFIX	specify the restart files for umbrella integration
OUTPUTPREFIX	specify the output prefix (default to the label name)
TEMP	the system temperature - needed when FRICTION is present. If not provided will be taken from MD code (if available)
EXTTEMP	the temperature of extended variables (default to system temperature)
DRR_RFILE	specifies the restart file (.drrstate file)
FMT	specify format for outfiles files (useful for decrease the number of digits in regtests)