CUSTOM

This is part of the function module

Calculate a combination of variables using a custom expression.

This action computes an arbitrary function of one or more collective variables. Arguments are chosen with the ARG keyword, and the function is provided with the FUNC string. Notice that this string should contain no space. Within FUNC, one can refer to the arguments as x,y,z, and t (up to four variables provided as ARG). This names can be customized using the VAR keyword (see examples below).

This function is implemented using the Lepton library, that allows to evaluate algebraic expressions and to automatically differentiate them.

If you want a function that depends not only on collective variables but also on time you can use the TIME action.

Examples

The following input tells plumed to perform a metadynamics using as a CV the difference between two distances.

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

contract shortcuts

dAB: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,12 The DISTANCE action with label dAB calculates a single scalar value
dAC: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,15 The DISTANCE action with label dAC calculates a single scalar value
diff: CUSTOM 
ARG
the input to this function. 
=dAB,dAC 
FUNC
compulsory keyword 
the function you wish to evaluate 
=y-x 
PERIODIC
compulsory keyword 
if the output of your function is periodic then you should specify the periodicity
of the function. 
=NO The CUSTOM action with label diff calculates a single scalar value
# notice: the previous line could be replaced with the following
# diff: COMBINE ARG=dAB,dAC COEFFICIENTS=-1,1
METAD 
ARG
the input for this action is the scalar output from one or more other actions. 
=diff 
SIGMA
compulsory keyword 
the widths of the Gaussian hills 
=0.1 
HEIGHT
the heights of the Gaussian hills. 
=0.5 
BIASFACTOR
use well tempered metadynamics and use this bias factor. 
=10 
PACE
compulsory keyword 
the frequency for hill addition 
=100 The METAD action with label 

dAB: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,12 The DISTANCE action with label dAB calculates a single scalar value
dAC: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,15 The DISTANCE action with label dAC calculates a single scalar value
# notice: the previous line could be replaced with the following
# diff: COMBINE ARG=dAB,dAC COEFFICIENTS=-1,1
METAD 
ARG
the input for this action is the scalar output from one or more other actions. 
=diff 
SIGMA
compulsory keyword 
the widths of the Gaussian hills 
=0.1 
HEIGHT
the heights of the Gaussian hills. 
=0.5 
BIASFACTOR
use well tempered metadynamics and use this bias factor. 
=10 
PACE
compulsory keyword 
the frequency for hill addition 
=100 The METAD action with label 
 (see also DISTANCE, COMBINE, and METAD). Notice that forces applied to diff will be correctly propagated to atoms 10, 12, and 15. Also notice that since CUSTOM is used without the VAR option the two arguments should be referred to as x and y in the expression FUNC. For simple functions such as this one it is possible to use COMBINE.
The following input tells plumed to print the angle between vectors identified by atoms 1,2 and atoms 2,3 its square (as computed from the x,y,z components) and the distance again as computed from the square root of the square. 
 Click on the labels of the actions for more information on what each action computes 
contract shortcuts




d1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,2 
COMPONENTS
( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x, 
 The DISTANCE action with label d1 calculates the following quantities:

 Quantity   
 Description  
d1.x
the x-component of the vector connecting the two atoms
d1.y
the y-component of the vector connecting the two atoms
d1.z
the z-component of the vector connecting the two atoms


d2: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=2,3 
COMPONENTS
( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x, 
 The DISTANCE action with label d2 calculates the following quantities:

 Quantity   
 Description  
d2.x
the x-component of the vector connecting the two atoms
d2.y
the y-component of the vector connecting the two atoms
d2.z
the z-component of the vector connecting the two atoms


theta: CUSTOM ...
   
   
ARG
the input to this function. 
=d1.x,d1.y,d1.z,d2.x,d2.y,d2.z 
   
VAR
the names to give each of the arguments in the function. 
=ax,ay,az,bx,by,bz 
   
FUNC
compulsory keyword 
the function you wish to evaluate 
=acos((ax*bx+ay*by+az*bz)/sqrt((ax*ax+ay*ay+az*az)*(bx*bx+by*by+bz*bz))) 
   
PERIODIC
compulsory keyword 
if the output of your function is periodic then you should specify the periodicity
of the function. 
=NO 
...The CUSTOM action with label theta calculates a single scalar value
PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=theta The PRINT action with label 


d1: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=1,2 
COMPONENTS
( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x, 
 The DISTANCE action with label d1 calculates the following quantities:

 Quantity   
 Description  
d1.x
the x-component of the vector connecting the two atoms
d1.y
the y-component of the vector connecting the two atoms
d1.z
the z-component of the vector connecting the two atoms


d2: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=2,3 
COMPONENTS
( default=off ) calculate the x, y and z components of the distance separately and
store them as label.x, 
 The DISTANCE action with label d2 calculates the following quantities:

 Quantity   
 Description  
d2.x
the x-component of the vector connecting the two atoms
d2.y
the y-component of the vector connecting the two atoms
d2.z
the z-component of the vector connecting the two atoms


PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=theta The PRINT action with label 
 (See also PRINT and DISTANCE).
Notice that this action implements a large number of functions (trigonometric, exp, log, etc). Among the useful functions, have a look at the step function (that is the Heaviside function). step(x) is defined as 1 when x is positive and 0 when x is negative. This allows for a straightforward implementation of if clauses.
For example, imagine that you want to implement a restraint that only acts when a distance is larger than 0.5. You can do it with 
 Click on the labels of the actions for more information on what each action computes 
contract shortcuts




d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,15 The DISTANCE action with label d calculates a single scalar value
m: CUSTOM 
ARG
the input to this function. 
=d 
FUNC
compulsory keyword 
the function you wish to evaluate 
=0.5*step(0.5-x)+x*step(x-0.5) 
PERIODIC
compulsory keyword 
if the output of your function is periodic then you should specify the periodicity
of the function. 
=NO The CUSTOM action with label m calculates a single scalar value
# check the function you are applying:
PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=d,m 
FILE
the name of the file on which to output these quantities 
=checkme The PRINT action with label 
RESTRAINT 
ARG
the arguments on which the bias is acting. 
=d 
AT
compulsory keyword 
the position of the restraint 
=0.5 
KAPPA
compulsory keyword ( default=0.0 )
specifies that the restraint is harmonic and what the values of the force constants
on each of the variables are 
=10.0 The RESTRAINT action with label 


d: DISTANCE 
ATOMS
the pair of atom that we are calculating the distance between. 
=10,15 The DISTANCE action with label d calculates a single scalar value
# check the function you are applying:
PRINT 
ARG
the input for this action is the scalar output from one or more other actions. 
=d,m 
FILE
the name of the file on which to output these quantities 
=checkme The PRINT action with label 
 (see also DISTANCE, PRINT, and RESTRAINT)
The meaning of the function 0.5*step(0.5-x)+x*step(x-0.5) is:

If x<0.5 (step(0.5-x)!=0) use 0.5
If x>0.5 (step(x-0.5)!=0) use x Notice that the same could have been obtained using an UPPER_WALLS However, with CUSTOM you can create way more complex definitions.

Warning
If you apply forces on the variable (as in the previous example) you should make sure that the variable is continuous! Conversely, if you are just analyzing a trajectory you can safely use discontinuous variables.
A possible continuity check with gnuplot is 
# this allow to step function to be used in gnuplot:
gnuplot> step(x)=0.5*(erf(x*10000000)+1)
# here you can test your function
gnuplot> p 0.5*step(0.5-x)+x*step(x-0.5)
Also notice that you can easily make logical operations on the conditions that you create. The equivalent of the AND operator is the product: step(1.0-x)*step(x-0.5) is only equal to 1 when x is between 0.5 and 1.0. By combining negation and AND you can obtain an OR. That is, 1-step(1.0-x)*step(x-0.5) is only equal to 1 when x is outside the 0.5-1.0 interval.
CUSTOM can be used in combination with DISTANCE to implement variants of the DISTANCE keyword that were present in PLUMED 1.3 and that allowed to compute the distance of a point from a line defined by two other points, or the progression along that line. 
 Click on the labels of the actions for more information on what each action computes 
contract shortcuts




# take center of atoms 1 to 10 as reference point 1
p1: CENTER 
ATOMS
the group of atoms that you are calculating the Gyration Tensor for. 
=1-10 The CENTER action with label p1 calculates the following quantities:

 Quantity   
 Description  
p1.x
PRINT ARG=onaxis,fromaxis
Notice that these equations have been used to combine RMSD from different snapshots of a protein so as to define progression (S) and distance (Z) variables [84].
Glossary of keywords and components

Description of components



 Quantity   
 Description    

 .#!value  
an arbitrary function   

Compulsory keywords



 PERIODIC  
if the output of your function is periodic then you should specify the periodicity of the function. If the output is not periodic you must state this using PERIODIC=NO   

 FUNC  
the function you wish to evaluate   

Options



 ARG  
the input to this function. You can use multiple instances of this keyword i.e. ARG1, ARG2, ARG3...   

 VAR  
the names to give each of the arguments in the function. If you have up to three arguments in your function you can use x, y and z to refer to them. Otherwise you must use this flag to give your variables names.   







  


    
   
    
     1.8.17