MAXENT

This is part of the bias module

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 Ref. [3] .

Warning

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) \]

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

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. 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

d1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=7,15 The DISTANCE action with label d1 calculates a single scalar value
d2: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=2,19 The DISTANCE action with label d2 calculates a single scalar value
restraint: MAXENT ...
   
ARG
the input for this action is the scalar output from one or more other actions. 
=d1,d2 
   
TYPE
compulsory keyword 
specify the restraint type. 
=EQUAL 
   
AT
compulsory keyword 
the position of the restraint 
=0.2,0.5 
   
KAPPA
compulsory keyword ( default=0.0 )
specifies the initial value for the learning rate 
=35000.0,35000.0 
   
TAU
compulsory keyword 
Specify the dumping time for the learning rate. 
=0.02,0.02 
   
PACE
the frequency for Lagrangian multipliers update 
=200 
   
TSTART
time from where to start averaging the Lagrangian multiplier. 
=100 
   
TEND
time in ps where to stop to compute the average of Lagrangian multiplier. 
=500 
   
...The MAXENT action with label restraint calculates the following quantities:

 Quantity   
 Description  
restraint.bias
the instantaneous value of the bias potential
restraint.force2
the instantaneous value of the squared force due to this bias potential
restraint.work
the instantaneous value of the work done by the biasing force
restraint.d1_coupling
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
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
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
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
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
Instantaneous values of the discrepancy between the observable and the restraint center This particular component measures this quantity for the input CV named d2


PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=restraint.bias The PRINT action with label 

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

d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=7,15 The DISTANCE action with label d calculates a single scalar value
restraint: MAXENT 
ARG
the input for this action is the scalar output from one or more other actions. 
=d 
TYPE
compulsory keyword 
specify the restraint type. 
=INEQUAL> 
AT
compulsory keyword 
the position of the restraint 
=0.02 
KAPPA
compulsory keyword ( default=0.0 )
specifies the initial value for the learning rate 
=35000.0 
TAU
compulsory keyword 
Specify the dumping time for the learning rate. 
=3 The MAXENT action with label restraint calculates the following quantities:

 Quantity   
 Description  
restraint.bias
the instantaneous value of the bias potential
restraint.force2
the instantaneous value of the squared force due to this bias potential
restraint.work
the instantaneous value of the work done by the biasing force
restraint.d_coupling
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
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
Instantaneous values of the discrepancy between the observable and the restraint center This particular component measures this quantity for the input CV named d


PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=restraint.bias The PRINT action with label 

(See also DISTANCE and PRINT).

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
work	the instantaneous value of the work done by the biasing force
_work	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.
_error	Instantaneous values of the discrepancy between the observable and the restraint center
_coupling	Instantaneous values of Lagrangian multipliers. They are also written by default in a separate output file.

Compulsory keywords

KAPPA	( default=0.0 ) specifies the initial value for the learning rate
TAU	Specify the dumping time for the learning rate.
TYPE	specify the restraint type. EQUAL to restrain the variable at a given equilibrium value INEQUAL< to restrain the variable to be smaller than a given value INEQUAL> to restrain the variable to be greater than a given value
AT	the position of the restraint

Options

NUMERICAL_DERIVATIVES	( default=off ) calculate the derivatives for these quantities numerically
REWEIGHT	( default=off ) to be used with plumed driver in order to reweight a trajectory a posteriori
NO_BROADCAST	( default=off ) If active will avoid Lagrangian multipliers to be communicated to other replicas.
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...
ERROR_TYPE	specify the prior on the error to use.GAUSSIAN: use a Gaussian prior LAPLACE: use a Laplace prior
TSTART	time from where to start averaging the Lagrangian multiplier. By default no average is computed, hence lambda is updated every PACE steps
TEND	time in ps where to stop to compute the average of Lagrangian multiplier. From this time until the end of the simulation Lagrangian multipliers are kept fix to the average computed between TSTART and TEND;
ALPHA	default=1.0; To be used with LAPLACE KEYWORD, allows to choose a prior function proportional to a Gaussian times an exponential function. ALPHA=1 correspond to the LAPLACE prior.
SIGMA	The typical errors expected on observable
FILE	Lagrangian multipliers output file. The default name is: label name followed by the string .LAGMULT
LEARN_REPLICA	In a multiple replica environment specify which is the reference replica. By default replica 0 will be used.
APPLY_WEIGHTS	Vector of weights containing 1 in correspondence of each replica that will receive the Lagrangian multiplier from the current one.
PACE	the frequency for Lagrangian multipliers update
PRINT_STRIDE	stride of Lagrangian multipliers output file. If no STRIDE is passed they are written every time they are updated (PACE).
FMT	specify format for Lagrangian multipliers files (useful to decrease the number of digits in regtests)
TEMP	the system temperature. This is required if you are reweighting.
RESTART	allows per-action setting of restart (YES/NO/AUTO)