Module: function

Description	Usage
actions that take arguments as input and that return values
Authors: The PLUMED core developers

Details

When performing biased dynamics or analyzing a trajectory you may wish to analyze/bias the value of some function of a set of collective variables rather than the values of the collective variables directly. You can do this with PLUMED by using the function that are available within this module.

In early versions of PLUMED the values that appeared in the input to these functions were always scalars.
However, from PLUMED 2.10 onwards some functions can also accept vectors, matrices or functions on grids in input. When the scalar-valued functions in this module are called in this way the function is applied elementwise to to the input vectors, matrices or functions on grid are returned and thus any values returned have the same type as the input arguments.

Dealing with periodicity

Notice that in many functions you should explicitly say to PLUMED whether the result is a periodic variable or not using the keyword PERIODIC. This is crucial to allow a variable to be properly based. To know if a function is periodic of not you should answer to the following question:

• Can my function change with a discontinuity when I move my atoms in a continuous manner?

In case the answer is no, than you should use PERIODIC=NO. In case the answer is yes, then you should consider the following question:

• Are the values of the function at the discontinuity always the same or do they change?

In case the answer is that they are the same, you should use PERIODIC=A,B where A is the smallest value and B is the largest value. In case the answer is that the values at the discontinuity are not always the same, then you cannot construct a variable that can be biased with PLUMED. Consider the following examples:

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

tThe TORSION action with label t calculates the following quantities:
 Quantity   
 Type   
 Description  
t
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
# When atoms are moved, t could jump suddenly from -pi to +pi

cThe MATHEVAL action with label c calculates the following quantities:
 Quantity   
 Type   
 Description  
c
scalar
an arbitrary function: MATHEVALAn alias to the CUSTOM function that can also be used to calaculate combinations of variables using a custom expression. More details ARGthe values input to this function=t FUNCthe function you wish to evaluate=x*x*x PERIODICif the output of your function is periodic then you should specify the periodicity of the function=-31.0062766802998,31.0062766802998
# When atoms are moved, c could jump suddenly from -pi**3 to +pi**3

# equivalently, we could have used:
# c: COMBINE ARG=t POWERS=3 PERIODIC=-31.0062766802998,31.0062766802998

# compute x/y/z components of the distance between atoms 1 and 10
dThe DISTANCE action with label d calculates the following quantities:
 Quantity   
 Type   
 Description  
d.x
scalar
the x-component of the vector connecting the two atoms
d.y
scalar
the y-component of the vector connecting the two atoms
d.z
scalar
the z-component of the vector connecting the two atoms: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,10 COMPONENTS calculate the x, y and z components of the distance separately and store them as label

# make a new variable equal to d.z but with the correct periodicity
dzThe COMBINE action with label dz calculates the following quantities:
 Quantity   
 Type   
 Description  
dz
scalar
a linear combination: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=d.z PERIODICif the output of your function is periodic then you should specify the periodicity of the function=-10,10
# here we assumed the system is in a orthorhombic box with z side = 20

Actions

The following actions are part of this module

Tags

FUNCTION COLVAR

FUNCTION: actions that take in one or multiple arguments and that return one or multiple arguments COLVAR: a function of a set of atomic positions that returns a scalar

Name	Description	Tags
BESSEL	Calculate the value of a Bessel function.	FUNCTION
BETWEEN	Use a switching function to determine how many of the input variables are within a certain range.	FUNCTION
COMBINE	Calculate a polynomial combination of a set of other variables.	FUNCTION
CUSTOM	Calculate a combination of variables using a custom expression.	FUNCTION
ENSEMBLE	Calculates the replica averaging of a collective variable over multiple replicas.	FUNCTION
FUNCPATHGENERAL	This function calculates path collective variables (PCVs) using an arbitrary combination of collective variables.	FUNCTION
FUNCPATHMSD	This function calculates path collective variables.	FUNCTION
FUNCSUMHILLS	This function is intended to be called by the command line tool sum_hills. It is meant to integrate a HILLS file or an HILLS file interpreted as a histogram in a variety of ways. It is, therefore, not expected that you use this during your dynamics (it will crash!)	FUNCTION
HIGHEST	This function can be used to find the highest colvar by magnitude in a set.	FUNCTION
LESS_THAN	Use a switching function to determine how many of the input variables are less than a certain cutoff.	FUNCTION
LOCALENSEMBLE	Calculates the average over multiple arguments.	FUNCTION
LOWEST	This function can be used to find the lowest colvar by magnitude in a set.	FUNCTION
MATHEVAL	An alias to the CUSTOM function that can also be used to calaculate combinations of variables using a custom expression.	FUNCTION
MEAN	Calculate the arithmetic mean of the elements in a vector	COLVAR
MOMENTS	Calculate central moments from the distribution of input quantities	FUNCTION
MORE_THAN	Use a switching function to determine how many of the input variables are more than a certain cutoff.	FUNCTION
PIECEWISE	Compute a piece wise straight line through its arguments that passes through a set of ordered control points.	FUNCTION
PRODUCT	Calculate the product of the input quantities	FUNCTION
SORT	This function can be used to sort colvars according to their magnitudes.	FUNCTION
STATS	Calculates statistical properties of a set of collective variables with respect to a set of reference values.	FUNCTION
SUM	Calculate the sum of the arguments	COLVAR