Shortcut: AVERAGE

Module	generic
Description	Usage
Calculate the ensemble average of a collective variable
output value	type
the value of the average	scalar/grid

Details and examples

Calculate the ensemble average of a collective variable

The ensemble average for a non-periodic, collective variable, $s$ is given by the following expression:

$$\langle s \rangle = \frac{ \sum_{t'=0}^t w(t') s(t') }{ \sum_{t'=0}^t w(t') }$$

Here the sum runs over a the trajectory and $s(t')$ is used to denote the value of the collective variable at time $t'$. The final quantity evaluated is a weighted average as the weights, If the simulation is unbiassed then all the $w(t')$ values in teh expression above are zero. If the simulation is biased then the $w(t')$ weights are set in a way that ensures the effect any bias has on the region of phase space sampled by the system is negated.

As the following example input shows you can use the AVERAGE shortcut to calculate the ensemble average of a CV using this formula:

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

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=1,2
d1aThe AVERAGE action with label d1a calculates the following quantities:
 Quantity   
 Type   
 Description  
d1a
scalar
the value of the average: AVERAGECalculate the ensemble average of a collective variable This action is a shortcut and it has hidden defaults. More details ARGthe quantity that is being averaged=d1
d1a: AVERAGECalculate the ensemble average of a collective variable This action is a shortcut and uses the defaults shown here. More details ARGthe quantity that is being averaged=d1  STRIDE the frequency with which to store data for averaging=1 CLEAR the frequency with whihc to clear the data that is being averaged=0
# PLUMED interprets the command:
# d1a: AVERAGE ARG=d1
# as follows (Click the red comment above to revert to the short version of the input):
d1a_weightThe CONSTANT action with label d1a_weight calculates the following quantities:
 Quantity   
 Type   
 Description  
d1a_weight
scalar
the constant value that was read from the plumed input: ONESCreate a constant vector with all elements equal to one More details SIZEthe number of ones that you would like to create=1
d1a_denomThe ACCUMULATE action with label d1a_denom calculates the following quantities:
 Quantity   
 Type   
 Description  
d1a_denom
scalar
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory More details ARGthe label of the argument that is being added to on each timestep=d1a_weight STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=0
d1a_prodThe CUSTOM action with label d1a_prod calculates the following quantities:
 Quantity   
 Type   
 Description  
d1a_prod
scalar
an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d1,d1a_weight FUNCthe function you wish to evaluate=x*y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
d1a_numerThe ACCUMULATE action with label d1a_numer calculates the following quantities:
 Quantity   
 Type   
 Description  
d1a_numer
scalar
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory More details ARGthe label of the argument that is being added to on each timestep=d1a_prod STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=0
d1aThe CUSTOM action with label d1a calculates the following quantities:
 Quantity   
 Type   
 Description  
d1a
scalar
an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d1a_numer,d1a_denom FUNCthe function you wish to evaluate=x/y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
# --- End of included input --- PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d1a FILEthe name of the file on which to output these quantities=colvar STRIDE the frequency with which the quantities of interest should be output=100

In this example no bias is acting on the system so the weights, $w(t')$ in the formulas above can thus all be set equal to one. The shortcut illustrates how the averaging is achieved by using the ACCUMULATE action.

When the variable is periodic (e.g. TORSION) and has a value, $s$, in $a \le s \le b$ the ensemble average is evaluated using:

$$\langle s \rangle = a + \frac{b - a}{2\pi} \arctan \left[ \frac{ \sum_{t'=0}^t w(t') \sin\left( \frac{2\pi [s(t')-a]}{b - a} \right) }{ \sum_{t'=0}^t w(t') \cos\left( \frac{2\pi [s(t')-a]}{b - a} \right) } \right]$$

You can see how ACCUMULATE and CUSTOM can be used to implement this formula by expanding the shortcuts in the following example input:

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

t1The TORSION action with label t1 calculates the following quantities:
 Quantity   
 Type   
 Description  
t1
scalar
the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=1,2,3,4
t1aThe AVERAGE action with label t1a calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a
scalar
the value of the average: AVERAGECalculate the ensemble average of a collective variable This action is a shortcut and it has hidden defaults. More details ARGthe quantity that is being averaged=t1 CLEAR the frequency with whihc to clear the data that is being averaged=100
t1a: AVERAGECalculate the ensemble average of a collective variable This action is a shortcut and uses the defaults shown here. More details ARGthe quantity that is being averaged=t1 CLEAR the frequency with whihc to clear the data that is being averaged=100  STRIDE the frequency with which to store data for averaging=1
# PLUMED interprets the command:
# t1a: AVERAGE ARG=t1 CLEAR=100
# as follows (Click the red comment above to revert to the short version of the input):
t1a_weightThe CONSTANT action with label t1a_weight calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_weight
scalar
the constant value that was read from the plumed input: ONESCreate a constant vector with all elements equal to one More details SIZEthe number of ones that you would like to create=1
t1a_denomThe ACCUMULATE action with label t1a_denom calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_denom
scalar
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory More details ARGthe label of the argument that is being added to on each timestep=t1a_weight STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=100
t1a_sinThe CUSTOM action with label t1a_sin calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_sin
scalar
an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=t1,t1a_weight FUNCthe function you wish to evaluate=y*sin((x--pi)/((pi--pi)/(pi+pi))) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
t1a_cosThe CUSTOM action with label t1a_cos calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_cos
scalar
an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=t1,t1a_weight FUNCthe function you wish to evaluate=y*cos((x--pi)/((pi--pi)/(pi+pi))) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
t1a_sinsumThe ACCUMULATE action with label t1a_sinsum calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_sinsum
scalar
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory More details ARGthe label of the argument that is being added to on each timestep=t1a_sin STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=100
t1a_cossumThe ACCUMULATE action with label t1a_cossum calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_cossum
scalar
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory More details ARGthe label of the argument that is being added to on each timestep=t1a_cos STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=100
t1aThe CUSTOM action with label t1a calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a
scalar
an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=t1a_sinsum,t1a_cossum,t1a_denom FUNCthe function you wish to evaluate=-pi+((pi--pi)/(pi+pi))*atan2(x/z,y/z) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=-pi,pi
# --- End of included input --- PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=t1a FILEthe name of the file on which to output these quantities=colvar STRIDE the frequency with which the quantities of interest should be output=100

Notice that by using the CLEAR keyword we have specified that block averages are to be calculated. Consequently, after 100 steps all the information acquired thus far in the simulation is forgotten and the process of averaging is begun again. The quantities output in the colvar file are thus the block averages taken over the first 100 frames of the trajectory, the block average over the second 100 frames of trajectory and so on.

If a bias is acting upon the system then the $w(t')$ values in the expression above are non-zero. You can calculate the $w(t') values by using REWEIGHT_BIAS or similar. To pass these weights to the average action you would then use an input something like the following:

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

t1The TORSION action with label t1 calculates the following quantities:
 Quantity   
 Type   
 Description  
t1
scalar
the TORSION involving these atoms: TORSIONCalculate one or multiple torsional angles. More details ATOMSthe four atoms involved in the torsional angle=1,2,3,4
RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=t1 ATthe position of the restraint=pi KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=100.
The RESTRAINT action with label  calculates the following quantities:
 Quantity   
 Description  
.bias
the instantaneous value of the bias potential
.force2
the instantaneous value of the squared force due to this bias potentialwwThe REWEIGHT_BIAS action with label ww calculates the following quantities:
 Quantity   
 Type   
 Description  
ww
scalar
the weight to use for this frame to negate the effect the bias: REWEIGHT_BIASCalculate weights for ensemble averages that negate the effect the bias has on the region of phase space explored This action has hidden defaults. More details TEMPthe system temperature=300
ww: REWEIGHT_BIASCalculate weights for ensemble averages that negate the effect the bias has on the region of phase space explored This action uses the defaults shown here. More details TEMPthe system temperature=300  ARG the biases that must be taken into account when reweighting=*.bias
t1aThe AVERAGE action with label t1a calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a
scalar
the value of the average: AVERAGECalculate the ensemble average of a collective variable This action is a shortcut and it has hidden defaults. More details ARGthe quantity that is being averaged=t1 LOGWEIGHTSthe logarithm of the quantity to use as the weights when calculating averages=ww CLEAR the frequency with whihc to clear the data that is being averaged=100
t1a: AVERAGECalculate the ensemble average of a collective variable This action is a shortcut and uses the defaults shown here. More details ARGthe quantity that is being averaged=t1 LOGWEIGHTSthe logarithm of the quantity to use as the weights when calculating averages=ww CLEAR the frequency with whihc to clear the data that is being averaged=100  STRIDE the frequency with which to store data for averaging=1
# PLUMED interprets the command:
# t1a: AVERAGE ARG=t1 LOGWEIGHTS=ww CLEAR=100
# as follows (Click the red comment above to revert to the short version of the input):
t1a_wsumThe COMBINE action with label t1a_wsum calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_wsum
scalar
a linear combination: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=ww PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
t1a_weightThe CUSTOM action with label t1a_weight calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_weight
scalar
an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=t1a_wsum FUNCthe function you wish to evaluate=exp(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
t1a_denomThe ACCUMULATE action with label t1a_denom calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_denom
scalar
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory More details ARGthe label of the argument that is being added to on each timestep=t1a_weight STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=100
t1a_sinThe CUSTOM action with label t1a_sin calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_sin
scalar
an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=t1,t1a_weight FUNCthe function you wish to evaluate=y*sin((x--pi)/((pi--pi)/(pi+pi))) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
t1a_cosThe CUSTOM action with label t1a_cos calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_cos
scalar
an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=t1,t1a_weight FUNCthe function you wish to evaluate=y*cos((x--pi)/((pi--pi)/(pi+pi))) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO
t1a_sinsumThe ACCUMULATE action with label t1a_sinsum calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_sinsum
scalar
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory More details ARGthe label of the argument that is being added to on each timestep=t1a_sin STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=100
t1a_cossumThe ACCUMULATE action with label t1a_cossum calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a_cossum
scalar
a sum calculated from the time series of the input quantity: ACCUMULATESum the elements of this value over the course of the trajectory More details ARGthe label of the argument that is being added to on each timestep=t1a_cos STRIDE the frequency with which the data should be collected and added to the quantity being averaged=1 CLEAR the frequency with which to clear all the accumulated data=100
t1aThe CUSTOM action with label t1a calculates the following quantities:
 Quantity   
 Type   
 Description  
t1a
scalar
an arbitrary function: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=t1a_sinsum,t1a_cossum,t1a_denom FUNCthe function you wish to evaluate=-pi+((pi--pi)/(pi+pi))*atan2(x/z,y/z) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=-pi,pi
# --- End of included input --- PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=t1a FILEthe name of the file on which to output these quantities=colvar STRIDE the frequency with which the quantities of interest should be output=100

This AVERAGE action in this input is a shortcut once again so by expanding it you can obtain a better understanding of how the formulas above are applied in this case.

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/grid	the quantity that is being averaged

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 quantity that is being averaged
STRIDE	compulsory	1	the frequency with which to store data for averaging
CLEAR	compulsory	0	the frequency with whihc to clear the data that is being averaged
LOGWEIGHTS	optional	not used	the logarithm of the quantity to use as the weights when calculating averages

deprecated keywords

The keywords in the following table can still be used with this action but have been deprecated

Keyword	Description
NORMALIZATION	Including this keyword in the input to this action makes no difference to the calculation performed it was used in older versions of PLUMED and is provided here for back compatibility only