Action: MAXENT

Module	bias
Description	Usage
Add a linear biasing potential on one or more variables that satisfies a maximum entropy principle.

Details and examples

Add a linear biasing potential on one or more variables that satisfies a maximum entropy principle.

Add a linear biasing potential on one or more variables $f_{i}\left(\boldsymbol{x}\right)$ satisfying the maximum entropy principle as proposed in the paper cited below.

unfinalized syntax

Notice that syntax is still under revision and might change

The resulting biasing potential is given by:

$V_{BIAS}(\boldsymbol{x},t)=K_{B}T\sum_{i=1}^{\#arguments}f_{i}(\boldsymbol{x},t)\lambda_{i}(t)$

Lagrangian multipliers $\lambda_{i}$ are updated, every PACE steps, according to the following update rule:

$\lambda_{i}=\lambda_{i}+\frac{k_{i}}{1+\frac{t}{\tau_{i}}}\left(f_{exp,i}+\xi_{i}\lambda_{i}-f_{i}(\boldsymbol{x})\right)$

The variable $k$ in the above expression sets the initial value of the learning rate and its units are $[observable]^{-2}ps^{-1}$ . This variable can be set with the keyword KAPPA. The number of components for any KAPPA vector must be equal to the number of arguments for the action.

The variable $\xi_{i}(\lambda)$ is related to the chosen prior to model experimental errors. If a GAUSSIAN prior is used then:

$\xi_{i}(\lambda)=-\lambda_{i}\sigma^{2}$

where $\sigma$ is the typical expected error on the observable $f_i$ . For a LAPLACE prior:

$\xi_{i}(\lambda)=-\frac{\lambda_{i}\sigma^{2}}{1-\frac{\lambda^{2}\sigma^{2}}{2}}$

The value of $\xi(\lambda,t)$ is written in output as a component named: argument name followed by the string _error. Setting $\sigma=0$ is equivalent to enforce a pure Maximum Entropy restraint without any noise modelling. This method can be also used to enforce inequality restraint as shown in following examples.

Notice that a similar method is available as EDS, although with different features and using a different optimization algorithm.

Examples

The following input tells plumed to restrain the distance between atoms 7 and 15 and the distance between atoms 2 and 19, at different equilibrium values, and to print the energy of the restraint. The Lagrangian multiplier will be printed on a file called restraint.LAGMULT with a stride set by the variable PACE to 200ps. Moreover plumed will compute the average of each Lagrangian multiplier in the window [TSTART,TEND] and use that to continue the simulations with fixed Lagrangian multipliers.

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

DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=7,15 LABELa label for the action so that its output can be referenced in the input to other actions=d1The DISTANCE action with label d1 calculates the following quantities: Quantity    Type    Description  
d1 scalar the DISTANCE between this pair of atoms
DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=2,19 LABELa label for the action so that its output can be referenced in the input to other actions=d2The DISTANCE action with label d2 calculates the following quantities: Quantity    Type    Description  
d2 scalar the DISTANCE between this pair of atoms
MAXENTAdd a linear biasing potential on one or more variables that satisfies a maximum entropy principle. More details ...
ARGthe labels of the scalars on which the bias will act=d1,d2
TYPEspecify the restraint type=EQUAL
ATthe position of the restraint=0.2,0.5
KAPPA specifies the initial value for the learning rate=35000.0,35000.0
TAUSpecify the dumping time for the learning rate=0.02,0.02
PACEthe frequency for Lagrangian multipliers update=200
TSTARTtime from where to start averaging the Lagrangian multiplier=100
TENDtime in ps where to stop to compute the average of Lagrangian multiplier=500
LABELa label for the action so that its output can be referenced in the input to other actions=restraintThe MAXENT action with label restraint calculates the following quantities: Quantity    Type    Description  
restraint.bias scalar the instantaneous value of the bias potential
restraint.force2 scalar the instantaneous value of the squared force due to this bias potential
restraint.work scalar the instantaneous value of the work done by the biasing force
restraint.d1_coupling scalar Instantaneous values of Lagrangian multipliers. They are also written by default in a separate output file. This particular component measures this quantity for the input CV named d1
restraint.d1_work scalar the instantaneous value of the work done by the biasing force for each argument. These quantities will named with the arguments of the bias followed by the character string _work. This particular component measures this quantity for the input CV named d1
restraint.d1_error scalar Instantaneous values of the discrepancy between the observable and the restraint center This particular component measures this quantity for the input CV named d1
restraint.d2_coupling scalar Instantaneous values of Lagrangian multipliers. They are also written by default in a separate output file. This particular component measures this quantity for the input CV named d2
restraint.d2_work scalar the instantaneous value of the work done by the biasing force for each argument. These quantities will named with the arguments of the bias followed by the character string _work. This particular component measures this quantity for the input CV named d2
restraint.d2_error scalar Instantaneous values of the discrepancy between the observable and the restraint center This particular component measures this quantity for the input CV named d2
... MAXENT
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=restraint.bias

Lagrangian multipliers will be printed on a file called restraint.bias The following input tells plumed to restrain the distance between atoms 7 and 15 to be greater than 0.2 and to print the energy of the restraint

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

DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=7,15 LABELa label for the action so that its output can be referenced in the input to other actions=dThe DISTANCE action with label d calculates the following quantities: Quantity    Type    Description  
d scalar the DISTANCE between this pair of atoms
MAXENTAdd a linear biasing potential on one or more variables that satisfies a maximum entropy principle. More details ARGthe labels of the scalars on which the bias will act=d TYPEspecify the restraint type=INEQUAL> ATthe position of the restraint=0.02 KAPPA specifies the initial value for the learning rate=35000.0 TAUSpecify the dumping time for the learning rate=3 LABELa label for the action so that its output can be referenced in the input to other actions=restraintThe MAXENT action with label restraint calculates the following quantities: Quantity    Type    Description  
restraint.bias scalar the instantaneous value of the bias potential
restraint.force2 scalar the instantaneous value of the squared force due to this bias potential
restraint.work scalar the instantaneous value of the work done by the biasing force
restraint.d_coupling scalar Instantaneous values of Lagrangian multipliers. They are also written by default in a separate output file. This particular component measures this quantity for the input CV named d
restraint.d_work scalar the instantaneous value of the work done by the biasing force for each argument. These quantities will named with the arguments of the bias followed by the character string _work. This particular component measures this quantity for the input CV named d
restraint.d_error scalar Instantaneous values of the discrepancy between the observable and the restraint center This particular component measures this quantity for the input CV named d
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=restraint.bias

(See also DISTANCE and PRINT).

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
work	scalar	the instantaneous value of the work done by the biasing force
_work	scalar	the instantaneous value of the work done by the biasing force for each argument
_error	scalar	Instantaneous values of the discrepancy between the observable and the restraint center
_coupling	scalar	Instantaneous values of Lagrangian multipliers

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
KAPPA	compulsory	0.0	specifies the initial value for the learning rate
TAU	compulsory	none	Specify the dumping time for the learning rate
TYPE	compulsory	none	specify the restraint type
AT	compulsory	none	the position of the restraint
NUMERICAL_DERIVATIVESThis keyword do not have examples	optional	false	calculate the derivatives for these quantities numerically
ERROR_TYPEThis keyword do not have examples	optional	not used	specify the prior on the error to use
TSTART	optional	not used	time from where to start averaging the Lagrangian multiplier
TEND	optional	not used	time in ps where to stop to compute the average of Lagrangian multiplier
ALPHAThis keyword do not have examples	optional	not used	default=1
SIGMAThis keyword do not have examples	optional	not used	The typical errors expected on observable
FILEThis keyword do not have examples	optional	not used	Lagrangian multipliers output file
LEARN_REPLICAThis keyword do not have examples	optional	not used	In a multiple replica environment specify which is the reference replica
APPLY_WEIGHTSThis keyword do not have examples	optional	not used	Vector of weights containing 1 in correspondence of each replica that will receive the Lagrangian multiplier from the current one
PACE	optional	not used	the frequency for Lagrangian multipliers update
PRINT_STRIDEThis keyword do not have examples	optional	not used	stride of Lagrangian multipliers output file
FMTThis keyword do not have examples	optional	not used	specify format for Lagrangian multipliers files (useful to decrease the number of digits in regtests)
REWEIGHTThis keyword do not have examples	optional	false	to be used with plumed driver in order to reweight a trajectory a posteriori
NO_BROADCASTThis keyword do not have examples	optional	false	If active will avoid Lagrangian multipliers to be communicated to other replicas
TEMPThis keyword do not have examples	optional	not used	the system temperature
RESTARTThis keyword do not have examples	optional	not used	allows per-action setting of restart (YES/NO/AUTO)

References

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

A. Cesari, A. Gil-Ley, G. Bussi, Combining Simulations and Solution Experiments as a Paradigm for RNA Force Field Refinement. Journal of Chemical Theory and Computation. 12, 6192–6200 (2016)

Quantity	Type	Description
d1	scalar	the DISTANCE between this pair of atoms