Action: VES_LINEAR_EXPANSION

Module	ves
Description	Usage
Linear basis set expansion bias.

Details and examples

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 go to the module page and select VES_BIAS from the tags dropdown. 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 go to the module page and select VES_TARGETDIST from the tags dropdown.

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 go to the module page and select VES_OPTIMIZER from the tags dropdown. 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 ves_optimizer (see the section before last for more details) 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 the paper cited below 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

bf1: BF_LEGENDRELegendre polynomials basis functions. More details ORDERThe order of the basis function expansion=_FILL_ MINIMUMThe minimum of the interval on which the basis functions are defined=_FILL_ MAXIMUMThe maximum of the interval on which the basis functions are defined=_FILL_

The BF_LEGENDRE action with label bf1 calculates somethingVES_LINEAR_EXPANSIONLinear basis set expansion bias. More details ...
 ARGthe labels of the scalars on which the bias will act=d1
 BASIS_FUNCTIONSthe label of the one dimensional basis functions that should be used=bf1
 TEMPthe system temperature - this is needed if the MD code does not pass the temperature to PLUMED=_FILL_
 GRID_BINSthe number of bins used for the grid=200
 LABELa label for the action so that its output can be referenced in the input to other actions=b1
... VES_LINEAR_EXPANSION

The VES_LINEAR_EXPANSION action with label b1 calculates the following quantities:
 Quantity   
 Description  
b1.bias
the instantaneous value of the bias potential
b1.force2
the instantaneous value of the squared force due to this bias potentialOPT_AVERAGED_SGDAveraged stochastic gradient decent with fixed step size. More details ...
 BIASthe label of the VES bias to be optimized=b1
 STRIDEthe frequency of updating the coefficients given in the number of MD steps=1000
 LABELa label for the action so that its output can be referenced in the input to other actions=o1
 STEPSIZEthe step size used for the optimization=_FILL_
 FES_OUTPUThow often the FES(s) should be written out to file=500
 COEFFS_OUTPUT how often the coefficients should be written to file=10
... OPT_AVERAGED_SGD
The OPT_AVERAGED_SGD action with label o1 calculates the following quantities:
 Quantity   
 Description  
o1.value
a scalar

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

bf1: BF_FOURIERFourier basis functions. More details  ORDERThe order of the basis function expansion=_FILL_ MINIMUMThe minimum of the interval on which the basis functions are defined=_FILL_ MAXIMUMThe maximum of the interval on which the basis functions are defined=_FILL_
The BF_FOURIER action with label bf1 calculates somethingbf2: BF_LEGENDRELegendre polynomials basis functions. More details ORDERThe order of the basis function expansion=_FILL_ MINIMUMThe minimum of the interval on which the basis functions are defined=_FILL_ MAXIMUMThe maximum of the interval on which the basis functions are defined=_FILL_

The BF_LEGENDRE action with label bf2 calculates somethingtd_wt: TD_WELLTEMPEREDWell-tempered target distribution (dynamic). More details BIASFACTORThe bias factor used for the well-tempered distribution=10.0

The TD_WELLTEMPERED action with label td_wt calculates somethingVES_LINEAR_EXPANSIONLinear basis set expansion bias. More details ...
 ARGthe labels of the scalars on which the bias will act=cv1,cv2
 BASIS_FUNCTIONSthe label of the one dimensional basis functions that should be used=bf1,bf2
 TEMPthe system temperature - this is needed if the MD code does not pass the temperature to PLUMED=_FILL_
 GRID_BINSthe number of bins used for the grid=100
 LABELa label for the action so that its output can be referenced in the input to other actions=b1
 TARGET_DISTRIBUTIONthe label of the target distribution to be used=td_wt
... VES_LINEAR_EXPANSION

The VES_LINEAR_EXPANSION action with label b1 calculates the following quantities:
 Quantity   
 Description  
b1.bias
the instantaneous value of the bias potential
b1.force2
the instantaneous value of the squared force due to this bias potentialOPT_AVERAGED_SGDAveraged stochastic gradient decent with fixed step size. More details ...
 BIASthe label of the VES bias to be optimized=b1
 STRIDEthe frequency of updating the coefficients given in the number of MD steps=1000
 LABELa label for the action so that its output can be referenced in the input to other actions=o1
 STEPSIZEthe step size used for the optimization=_FILL_
 FES_OUTPUThow often the FES(s) should be written out to file=500
 COEFFS_OUTPUT how often the coefficients should be written to file=10
 TARGETDIST_STRIDEstride for updating a target distribution that is iteratively updated during the optimization=500
... OPT_AVERAGED_SGD
The OPT_AVERAGED_SGD action with label o1 calculates the following quantities:
 Quantity   
 Description  
o1.value
a scalar

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

bf1: BF_LEGENDRELegendre polynomials basis functions. More details ORDERThe order of the basis function expansion=_FILL_ MINIMUMThe minimum of the interval on which the basis functions are defined=_FILL_ MAXIMUMThe maximum of the interval on which the basis functions are defined=_FILL_
The BF_LEGENDRE action with label bf1 calculates somethingbf2: BF_LEGENDRELegendre polynomials basis functions. More details ORDERThe order of the basis function expansion=_FILL_ MINIMUMThe minimum of the interval on which the basis functions are defined=_FILL_ MAXIMUMThe maximum of the interval on which the basis functions are defined=_FILL_

The BF_LEGENDRE action with label bf2 calculates somethingVES_LINEAR_EXPANSIONLinear basis set expansion bias. More details ...
 ARGthe labels of the scalars on which the bias will act=cv1,cv2
 BASIS_FUNCTIONSthe label of the one dimensional basis functions that should be used=bf1,bf2
 TEMPthe system temperature - this is needed if the MD code does not pass the temperature to PLUMED=_FILL_
 GRID_BINSthe number of bins used for the grid=100
 LABELa label for the action so that its output can be referenced in the input to other actions=b1
 BIAS_CUTOFFcutoff 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
... VES_LINEAR_EXPANSION

The VES_LINEAR_EXPANSION action with label b1 calculates the following quantities:
 Quantity   
 Description  
b1.bias
the instantaneous value of the bias potential
b1.force2
the instantaneous value of the squared force due to this bias potentialOPT_AVERAGED_SGDAveraged stochastic gradient decent with fixed step size. More details ...
 BIASthe label of the VES bias to be optimized=b1
 STRIDEthe frequency of updating the coefficients given in the number of MD steps=1000
 LABELa label for the action so that its output can be referenced in the input to other actions=o1
 STEPSIZEthe step size used for the optimization=_FILL_
 FES_OUTPUThow often the FES(s) should be written out to file=500
 COEFFS_OUTPUT how often the coefficients should be written to file=10
 TARGETDIST_STRIDEstride for updating a target distribution that is iteratively updated during the optimization=500
... OPT_AVERAGED_SGD
The OPT_AVERAGED_SGD action with label o1 calculates the following quantities:
 Quantity   
 Description  
o1.value
a scalar

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

bf1: BF_LEGENDRELegendre polynomials basis functions. More details ORDERThe order of the basis function expansion=_FILL_ MINIMUMThe minimum of the interval on which the basis functions are defined=_FILL_ MAXIMUMThe maximum of the interval on which the basis functions are defined=_FILL_
The BF_LEGENDRE action with label bf1 calculates somethingbf2: BF_LEGENDRELegendre polynomials basis functions. More details ORDERThe order of the basis function expansion=_FILL_ MINIMUMThe minimum of the interval on which the basis functions are defined=_FILL_ MAXIMUMThe maximum of the interval on which the basis functions are defined=_FILL_

The BF_LEGENDRE action with label bf2 calculates somethingVES_LINEAR_EXPANSIONLinear basis set expansion bias. More details ...
 ARGthe labels of the scalars on which the bias will act=cv1,cv2
 BASIS_FUNCTIONSthe label of the one dimensional basis functions that should be used=bf1,bf2
 TEMPthe system temperature - this is needed if the MD code does not pass the temperature to PLUMED=_FILL_
 GRID_BINSthe number of bins used for the grid=100
 LABELa label for the action so that its output can be referenced in the input to other actions=b1
 BIAS_CUTOFFcutoff 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
 COEFFSread in the coefficients from files=coeffs_final.data
... VES_LINEAR_EXPANSION
The VES_LINEAR_EXPANSION action with label b1 calculates the following quantities:
 Quantity   
 Description  
b1.bias
the instantaneous value of the bias potential
b1.force2
the instantaneous value of the squared force due to this bias potential

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
force2	scalar	the instantaneous value of the squared force due to this bias potential

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
BASIS_FUNCTIONS	compulsory	none	the label of the one dimensional basis functions that should be used
GRID_FMT	compulsory	%14.9f	the format to use when outputting the numbers in the grids
NUMERICAL_DERIVATIVES	optional	false	calculate the derivatives for these quantities numerically
TEMP	optional	not used	the system temperature - this is needed if the MD code does not pass the temperature to PLUMED
BIAS_FILE	optional	not used	filename of the file on which the bias should be written out
FES_FILE	optional	not used	filename of the file on which the FES should be written out
TARGETDIST_FILE	optional	not used	filename of the file on which the target distribution should be written out
OPTIMIZATION_THRESHOLD	optional	not used	Threshold value to turn off optimization of localized basis functions
COEFFS	optional	not used	read in the coefficients from files
TARGET_DISTRIBUTION	optional	not used	the label of the target distribution to be used
BIAS_CUTOFF	optional	not used	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	optional	not used	the lambda value used in the Fermi switching function for the bias cutoff (BIAS_CUTOFF), the default value is 10
GRID_BINS	optional	not used	the number of bins used for the grid
PROJ_ARG	optional	not used	arguments for doing projections of the FES or the target distribution

References

More information about how this action can be used is available in the following articles:

• J. McCarty, O. Valsson, P. Tiwary, M. Parrinello, Variationally Optimized Free-Energy Flooding for Rate Calculation. Physical Review Letters. 115 (2015)