Action: FISST

Module	fisst
Description	Usage
Compute and apply the optimal linear force on an observable to enhance sampling of conformational distributions over a range of applied forces.

Details and examples

Compute and apply the optimal linear force on an observable to enhance sampling of conformational distributions over a range of applied forces.

This method is described in the paper cited below

If the system's Hamiltonian is given by:

$H(\vec{p},\vec{q}) = \sum_{j} \frac{p_j^2}{2m_j} + U(\vec{q}),$

This bias modifies the Hamiltonian to be:

$H'(\vec{p},\vec{q}) = H(\vec{p},\vec{q}) - \bar{F} Q$

where for CV $Q$ , a coupling constant ${\bar{F}}$ is determined adaptively according to the FISST algorithm.

Specifically,

$\bar{F}(Q)=\frac{ \int_{F_{min}}^{F_{max}} e^{\beta F Q(\vec{q})} \omega(F) F dF}{\int_{F_{min}}^{F_{max}} e^{\beta F Q(\vec{q})} \omega(F) dF},$

where $\vec{q}$ are the molecular coordinates of the system, and $w(F)$ is a weighting function that is learned on the fly for each force by the FISST algorithm (starting from an initial weight distribution, uniform by default).

The target for $w(F)=1/Z_q(F)$ , where

$Z_q(F) \equiv \int d\vec{q} e^{-\beta U(\vec{q}) + \beta F Q(\vec{q})}.$

FISST also computes and writes Observable Weights $W_F(\vec{q}_t)$ for a molecular configuration at time $t$ , so that averages of other quantities $A(\vec{q})$ can be reconstructed later at different force values (over a trajectory with $T$ samples):

$\langle A \rangle_F = \frac{1}{T} \sum_t W_F(\vec{q}_t) A(\vec{q}_t).$

Examples

In the following example, an adaptive restraint is learned to bias the distance between two atoms in a system, for a force range of 0-100 pN.

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

UNITSThis command sets the internal units for the code. More details LENGTHthe units of lengths=A TIMEthe units of time=fs ENERGYthe units of energy=kcal/mol

The UNITS action with label  calculates somethingb1The GROUP action with label b1 calculates the following quantities: Quantity    Type    Description  
b1 atoms indices of atoms specified in GROUP: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=1
b2The GROUP action with label b2 calculates the following quantities: Quantity    Type    Description  
b2 atoms indices of atoms specified in GROUP: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=12

dendThe DISTANCE action with label dend calculates the following quantities: Quantity    Type    Description  
dend 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=b1,b2

#The conversion factor is 69.4786 pN = 1 kcal/mol/Angstrom

#0 pN to 100 pN
fThe FISST action with label f calculates the following quantities: Quantity    Type    Description  
f.bias scalar the instantaneous value of the bias potential
f.force2 scalar squared value of force from the bias.
f.dend_fbar scalar For each named CV biased, there will be a corresponding output CV_fbar storing the current linear bias prefactor. This particular component measures this quantity for the input CV named dend: FISSTCompute and apply the optimal linear force on an observable to enhance sampling of conformational distributions over a range of applied forces. This action has hidden defaults. More details MIN_FORCEMinimum force (per CV) to use for sampling=0 MAX_FORCEMaximum force (per CV) to use for sampling=1.44 PERIODSteps corresponding to the learning rate=100 NINTERPOLATENumber of grid points on which to do interpolation=31 ARGthe labels of the scalars on which the bias will act=dend OUT_RESTARTOutput file for all information needed to continue FISST simulation=pull.restart.txt OUT_OBSERVABLEOutput file putting weights needed to compute observables at different force values=pull.observable.txt OBSERVABLE_FREQ=1000
f: FISSTCompute and apply the optimal linear force on an observable to enhance sampling of conformational distributions over a range of applied forces. This action uses the defaults shown here. More details MIN_FORCEMinimum force (per CV) to use for sampling=0 MAX_FORCEMaximum force (per CV) to use for sampling=1.44 PERIODSteps corresponding to the learning rate=100 NINTERPOLATENumber of grid points on which to do interpolation=31 ARGthe labels of the scalars on which the bias will act=dend OUT_RESTARTOutput file for all information needed to continue FISST simulation=pull.restart.txt OUT_OBSERVABLEOutput file putting weights needed to compute observables at different force values=pull.observable.txt OBSERVABLE_FREQ=1000  CENTER The CV value at which the applied bias energy will be zero=0

PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=dend,f.dend_fbar,f.bias,f.force2 FILEthe name of the file on which to output these quantities=pull.colvar.txt STRIDE the frequency with which the quantities of interest should be output=1000

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	squared value of force from the bias
_fbar	scalar	For each named CV biased, there will be a corresponding output CV_fbar storing the current linear bias prefactor

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
PERIOD	compulsory	none	Steps corresponding to the learning rate
NINTERPOLATE	compulsory	none	Number of grid points on which to do interpolation
MIN_FORCE	compulsory	none	Minimum force (per CV) to use for sampling
MAX_FORCE	compulsory	none	Maximum force (per CV) to use for sampling
CENTER	compulsory	0	The CV value at which the applied bias energy will be zero
NUMERICAL_DERIVATIVESThis keyword do not have examples	optional	false	calculate the derivatives for these quantities numerically
RESET_PERIODThis keyword do not have examples	optional	not used	Reset the learning statistics every time this number of steps comes around
KBTThis keyword do not have examples	optional	not used	The system temperature in units of KB*T
INITIAL_WEIGHT_DISTThis keyword do not have examples	optional	not used	Starting distribution for the force weights (options: UNIFORM, EXP, GAUSS)
INITIAL_WEIGHT_RATEThis keyword do not have examples	optional	not used	Rate of decay for exponential and gaussian distributions
RESTART_FMTThis keyword do not have examples	optional	not used	the format that should be used to output real numbers in FISST restarts
OUT_RESTART	optional	not used	Output file for all information needed to continue FISST simulation
IN_RESTARTThis keyword do not have examples	optional	not used	Read this file to continue an FISST simulation
OUT_OBSERVABLE	optional	not used	Output file putting weights needed to compute observables at different force values
OBSERVABLE_FREQ	optional	not used
FREEZEThis keyword do not have examples	optional	false	Fix bias weights at current level (only used for restarting)
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:

M. J. Hartmann, Y. Singh, E. Vanden-Eijnden, G. M. Hocky, Infinite switch simulated tempering in force (FISST). The Journal of Chemical Physics. 152 (2020)

Quantity	Type	Description
b1	atoms	indices of atoms specified in GROUP