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

Linear basis set expansion bias.

This VES bias action takes the bias potential to be a linear expansion in some basis set that is written as a product of one-dimensional basis functions. For example, for one CV the bias would be written as

\[ V(s_{1};\boldsymbol{\alpha}) = \sum_{i_{1}} \alpha_{i_{1}} \, f_{i_{1}}(s_{1}), \]

while for two CVs it is written as

\[ V(s_{1},s_{2};\boldsymbol{\alpha}) = \sum_{i_{1},i_{2}} \alpha_{i_{1},i_{2}} \, f_{i_{1}}(s_{1}) \, f_{i_{2}}(s_{2}) \]

where \(\boldsymbol{\alpha}\) is the set of expansion coefficients that are optimized within VES. With an appropriate choice of the basis functions it is possible to represent any generic free energy surface. The relationship between the bias and the free energy surface is given by

\[ V(\mathbf{s}) = - F(\mathbf{s}) - \frac{1}{\beta} \log p(\mathbf{s}). \]

where \(p(\mathbf{s})\) is the target distribution that is employed in the VES simulation.

Basis Functions

Various one-dimensional basis functions are available in the VES code, see the complete list here. At the current moment we recommend to use Legendre polynomials (BF_LEGENDRE) for non-periodic CVs and Fourier basis functions (BF_FOURIER) for periodic CV (e.g. dihedral angles).

To use basis functions within VES_LINEAR_EXPANSION you first need to define them in the input file before the VES_LINEAR_EXPANSION action and then give their labels using the BASIS_FUNCTIONS keyword.

Target Distributions

Various target distributions \(p(\mathbf{s})\) are available in the VES code, see the complete list here.

To use a target distribution within VES_LINEAR_EXPANSION you first need to define it in the input file before the VES_LINEAR_EXPANSION action and then give its label using the TARGET_DISTRIBUTION keyword. The default behavior if no TARGET_DISTRIBUTION is given is to employ a uniform target distribution.

Some target distribution, like the well-tempered one (TD_WELLTEMPERED), are dynamic and need to be iteratively updated during the optimization.

Optimizer

In order to optimize the coefficients you will need to use VES_LINEAR_EXPANSION in combination with an optimizer, see the list of optimizers available in the VES code here. At the current moment we recommend to use the averaged stochastic gradient decent optimizer (OPT_AVERAGED_SGD).

The optimizer should be defined after the VES_LINEAR_EXPANSION action.

Grid

Internally the code uses grids to calculate the basis set averages over the target distribution that is needed for the gradient. The same grid is also used for the output files (see next section). The size of the grid is determined by the GRID_BINS keyword. By default it has 100 grid points in each dimension, and generally this value should be sufficient.

Outputting Free Energy Surfaces and Other Files

It is possible to output on-the-fly during the simulation the free energy surface estimated from the bias potential. How often this is done is specified within the optimizer by using the FES_OUTPUT keyword. The filename is specified by the FES_FILE keyword, but by default is it fes.LABEL.data, with an added suffix indicating the iteration number (iter-#).

For multi-dimensional case is it possible to also output projections of the free energy surfaces. The arguments for which to do these projections is specified using the numbered PROJ_ARG keywords. For these files a suffix indicating the projection (proj-#) will be added to the filenames. You will also need to specify the frequency of the output by using the FES_PROJ_OUTPUT keyword within the optimizer.

It is also possible to output the bias potential itself, for this the relevant keyword is BIAS_OUTPUT within the optimizer. The filename is specified by the BIAS_FILE keyword, but by default is it bias.LABEL.data, with an added suffix indicating the iteration number (iter-#).

Furthermore is it possible to output the target distribution, and its projections (i.e. marginal distributions). The filenames of these files are specified with the TARGETDIST_FILE, but by default is it targetdist.LABEL.data. The logarithm of the target distribution will also be outputted to file that has the added suffix log. For static target distribution these files will be outputted in the beginning of the simulation while for dynamic ones you will need to specify the frequency of the output by using the TARGETDIST_OUTPUT and TARGETDIST_PROJ_OUTPUT keywords within the optimizer.

It is also possible to output free energy surfaces and bias in post processing by using the VES_OUTPUT_FES action. However, be aware that this action does does not support dynamic target distribution (e.g. well-tempered).

Static Bias

It is also possible to use VES_LINEAR_EXPANSION as a static bias that uses previously obtained coefficients. In this case the coefficients should be read in from the coefficient file given in the COEFFS keyword.

Bias Cutoff

It is possible to impose a cutoff on the bias potential using the procedure introduced in [77] such that the free energy surface is only flooded up to a certain value. The bias that results from this procedure can then be used as a static bias for obtaining kinetic rates. The value of the cutoff is given by the BIAS_CUTOFF keyword. To impose the cutoff the code uses a Fermi switching function \(1/(1+e^{\lambda x})\) where the parameter \(\lambda\) controls how sharply the switchingfunction goes to zero. The default value is \(\lambda=10\) but this can be changed by using the BIAS_CUTOFF_FERMI_LAMBDA keyword.

Examples

In the following example we run a VES_LINEAR_EXPANSION for one CV using a Legendre basis functions (BF_LEGENDRE) and a uniform target distribution as no target distribution is specified. The coefficients are optimized using averaged stochastic gradient descent optimizer (OPT_AVERAGED_SGD). Within the optimizer we specify that the FES should be outputted to file every 500 coefficients iterations (the FES_OUTPUT keyword). Parameters that are very specific to the problem at hand, like the order of the basis functions, the interval on which the basis functions are defined, and the step size used in the optimizer, are left unfilled.

Click on the labels of the actions for more information on what each action computes
tested on master
bf1: BF_LEGENDRE 
ORDER
compulsory keyword The order of the basis function expansion.
=__
MINIMUM
compulsory keyword The minimum of the interval on which the basis functions are defined.
=__
MAXIMUM
compulsory keyword The maximum of the interval on which the basis functions are defined.
=__ b1: VES_LINEAR_EXPANSION ...
ARG
the input for this action is the scalar output from one or more other actions.
=d1
BASIS_FUNCTIONS
compulsory keyword the label of the one dimensional basis functions that should be used.
=bf1
TEMP
the system temperature - this is needed if the MD code does not pass the temperature to PLUMED.
=__
GRID_BINS
the number of bins used for the grid.
=200 ... o1: OPT_AVERAGED_SGD ...
BIAS
compulsory keyword the label of the VES bias to be optimized
=b1
STRIDE
compulsory keyword the frequency of updating the coefficients given in the number of MD steps.
=1000
STEPSIZE
compulsory keyword the step size used for the optimization
=__
FES_OUTPUT
how often the FES(s) should be written out to file.
=500
COEFFS_OUTPUT
compulsory keyword ( default=100 ) how often the coefficients should be written to file.
=10 ...

In the following example we employ VES_LINEAR_EXPANSION for two CVs, The first CV is periodic and therefore we employ a Fourier basis functions (BF_LEGENDRE) while the second CV is non-periodic so we employ a Legendre polynomials as in the previous example. For the target distribution we employ a well-tempered target distribution (TD_WELLTEMPERED), which is dynamic and needs to be iteratively updated with a stride that is given using the TARGETDIST_STRIDE within the optimizer.

Click on the labels of the actions for more information on what each action computes
tested on master
bf1: BF_FOURIER 
ORDER
compulsory keyword The order of the basis function expansion.
=__
MINIMUM
compulsory keyword The minimum of the interval on which the basis functions are defined.
=__
MAXIMUM
compulsory keyword The maximum of the interval on which the basis functions are defined.
=__ bf2: BF_LEGENDRE
ORDER
compulsory keyword The order of the basis function expansion.
=__
MINIMUM
compulsory keyword The minimum of the interval on which the basis functions are defined.
=__
MAXIMUM
compulsory keyword The maximum of the interval on which the basis functions are defined.
=__ td_wt: TD_WELLTEMPERED
BIASFACTOR
compulsory keyword The bias factor used for the well-tempered distribution.
=10.0 b1: VES_LINEAR_EXPANSION ...
ARG
the input for this action is the scalar output from one or more other actions.
=cv1,cv2
BASIS_FUNCTIONS
compulsory keyword the label of the one dimensional basis functions that should be used.
=bf1,bf2
TEMP
the system temperature - this is needed if the MD code does not pass the temperature to PLUMED.
=__
GRID_BINS
the number of bins used for the grid.
=100
TARGET_DISTRIBUTION
the label of the target distribution to be used.
=td_wt ... o1: OPT_AVERAGED_SGD ...
BIAS
compulsory keyword the label of the VES bias to be optimized
=b1
STRIDE
compulsory keyword the frequency of updating the coefficients given in the number of MD steps.
=1000
STEPSIZE
compulsory keyword the step size used for the optimization
=__
FES_OUTPUT
how often the FES(s) should be written out to file.
=500
COEFFS_OUTPUT
compulsory keyword ( default=100 ) how often the coefficients should be written to file.
=10
TARGETDIST_STRIDE
stride for updating a target distribution that is iteratively updated during the optimization.
=500 ...

In the following example we employ a bias cutoff such that the bias only fills the free energy landscape up a certain level. In this case the target distribution is also dynamic and needs to iteratively updated.

Click on the labels of the actions for more information on what each action computes
tested on master
bf1: BF_LEGENDRE 
ORDER
compulsory keyword The order of the basis function expansion.
=__
MINIMUM
compulsory keyword The minimum of the interval on which the basis functions are defined.
=__
MAXIMUM
compulsory keyword The maximum of the interval on which the basis functions are defined.
=__ bf2: BF_LEGENDRE
ORDER
compulsory keyword The order of the basis function expansion.
=__
MINIMUM
compulsory keyword The minimum of the interval on which the basis functions are defined.
=__
MAXIMUM
compulsory keyword The maximum of the interval on which the basis functions are defined.
=__ b1: VES_LINEAR_EXPANSION ...
ARG
the input for this action is the scalar output from one or more other actions.
=cv1,cv2
BASIS_FUNCTIONS
compulsory keyword the label of the one dimensional basis functions that should be used.
=bf1,bf2
TEMP
the system temperature - this is needed if the MD code does not pass the temperature to PLUMED.
=__
GRID_BINS
the number of bins used for the grid.
=100
BIAS_CUTOFF
cutoff the bias such that it only fills the free energy surface up to certain level F_cutoff, here you should give the value of the F_cutoff.
=20.0 ... o1: OPT_AVERAGED_SGD ...
BIAS
compulsory keyword the label of the VES bias to be optimized
=b1
STRIDE
compulsory keyword the frequency of updating the coefficients given in the number of MD steps.
=1000
STEPSIZE
compulsory keyword the step size used for the optimization
=__
FES_OUTPUT
how often the FES(s) should be written out to file.
=500
COEFFS_OUTPUT
compulsory keyword ( default=100 ) how often the coefficients should be written to file.
=10
TARGETDIST_STRIDE
stride for updating a target distribution that is iteratively updated during the optimization.
=500 ...

The optimized bias potential can then be used as a static bias for obtaining kinetics. For this you need read in the final coefficients from file (e.g. coeffs_final.data in this case) by using the COEFFS keyword (also, no optimizer should be defined in the input)

Click on the labels of the actions for more information on what each action computes
tested on master
bf1: BF_LEGENDRE 
ORDER
compulsory keyword The order of the basis function expansion.
=__
MINIMUM
compulsory keyword The minimum of the interval on which the basis functions are defined.
=__
MAXIMUM
compulsory keyword The maximum of the interval on which the basis functions are defined.
=__ bf2: BF_LEGENDRE
ORDER
compulsory keyword The order of the basis function expansion.
=__
MINIMUM
compulsory keyword The minimum of the interval on which the basis functions are defined.
=__
MAXIMUM
compulsory keyword The maximum of the interval on which the basis functions are defined.
=__ b1: VES_LINEAR_EXPANSION ...
ARG
the input for this action is the scalar output from one or more other actions.
=cv1,cv2
BASIS_FUNCTIONS
compulsory keyword the label of the one dimensional basis functions that should be used.
=bf1,bf2
TEMP
the system temperature - this is needed if the MD code does not pass the temperature to PLUMED.
=__
GRID_BINS
the number of bins used for the grid.
=100
BIAS_CUTOFF
cutoff the bias such that it only fills the free energy surface up to certain level F_cutoff, here you should give the value of the F_cutoff.
=20.0
COEFFS
read in the coefficients from files.
=coeffs_final.data ...
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
force2 the instantaneous value of the squared force due to this bias potential.
Compulsory keywords
BASIS_FUNCTIONS the label of the one dimensional basis functions that should be used.
Options
NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

TEMP the system temperature - this is needed if the MD code does not pass the temperature to PLUMED.
BIAS_FILE filename of the file on which the bias should be written out. By default it is bias.LABEL.data. Note that suffixes indicating the iteration number (iter-#) are added to the filename when optimizing coefficients.
FES_FILE filename of the file on which the FES should be written out. By default it is fes.LABEL.data. Note that suffixes indicating the iteration number (iter-#) are added to the filename when optimizing coefficients.
TARGETDIST_FILE filename of the file on which the target distribution should be written out. By default it is targetdist.LABEL.data. Note that suffixes indicating the iteration number (iter-#) are added to the filename when optimizing coefficients and the target distribution is dynamic.
COEFFS read in the coefficients from files.
TARGET_DISTRIBUTION the label of the target distribution to be used.
BIAS_CUTOFF cutoff the bias such that it only fills the free energy surface up to certain level F_cutoff, here you should give the value of the F_cutoff.
BIAS_CUTOFF_FERMI_LAMBDA the lambda value used in the Fermi switching function for the bias cutoff (BIAS_CUTOFF), the default value is 10.0.
GRID_BINS the number of bins used for the grid. The default value is 100 bins per dimension.
PROJ_ARG arguments for doing projections of the FES or the target distribution. You can use multiple instances of this keyword i.e. PROJ_ARG1, PROJ_ARG2, PROJ_ARG3...
ARG the input for this action is the scalar output from one or more other actions. The particular scalars that you will use are referenced using the label of the action. If the label appears on its own then it is assumed that the Action calculates a single scalar value. The value of this scalar is thus used as the input to this new action. If * or *.* appears the scalars calculated by all the proceeding actions in the input file are taken. Some actions have multi-component outputs and each component of the output has a specific label. For example a DISTANCE action labelled dist may have three components x, y and z. To take just the x component you should use dist.x, if you wish to take all three components then use dist.*.More information on the referencing of Actions can be found in the section of the manual on the PLUMED Getting Started. Scalar values can also be referenced using POSIX regular expressions as detailed in the section on Regular Expressions. To use this feature you you must compile PLUMED with the appropriate flag. You can use multiple instances of this keyword i.e. ARG1, ARG2, ARG3...