MAXENT
This is part of the bias module

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
tested on master
d1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between.
=7,15 d2: DISTANCE
ATOMS
the pair of atom that we are calculating the distance between.
=2,19 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 ... PRINT
ARG
the input for this action is the scalar output from one or more other actions.
=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
tested on master
d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between.
=7,15 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 PRINT
ARG
the input for this action is the scalar output from one or more other actions.
=restraint.bias

(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)