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

dAB:DISTANCEATOMS=10,12the pair of atom that we are calculating the distance between.dAC:DISTANCEATOMS=10,15the pair of atom that we are calculating the distance between.diff:CUSTOMARG=the input for this action is the scalar output from one or more other actions.dAB,dACFUNC=y-xcompulsory keywordthe function you wish to evaluatePERIODIC=NO # notice: the previous line could be replaced with the following # diff: COMBINE ARG=dAB,dAC COEFFICIENTS=-1,1 METADcompulsory keywordif the output of your function is periodic then you should specify the periodicity of the function.ARG=the input for this action is the scalar output from one or more other actions.diffSIGMA=0.1compulsory keywordthe widths of the Gaussian hillsHEIGHT=0.5the heights of the Gaussian hills.BIASFACTOR=10use well tempered metadynamics and use this bias factor.PACE=100compulsory keywordthe frequency for hill addition

(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

d1:DISTANCEATOMS=1,2the pair of atom that we are calculating the distance between.COMPONENTS( default=off ) calculate the x, y and z components of the distance separately and store them as label.x,d2:DISTANCEATOMS=2,3the pair of atom that we are calculating the distance between.COMPONENTS( default=off ) calculate the x, y and z components of the distance separately and store them as label.x,theta:CUSTOM ...ARG=the input for this action is the scalar output from one or more other actions.d1.x,d1.y,d1.z,d2.x,d2.y,d2.zVAR=ax,ay,az,bx,by,bzthe names to give each of the arguments in the function.FUNC=acos((ax*bx+ay*by+az*bz)/sqrt((ax*ax+ay*ay+az*az)*(bx*bx+by*by+bz*bz)))compulsory keywordthe function you wish to evaluatePERIODIC=NO ... PRINTcompulsory keywordif the output of your function is periodic then you should specify the periodicity of the function.ARG=the input for this action is the scalar output from one or more other actions.theta

(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

d:DISTANCEATOMS=10,15the pair of atom that we are calculating the distance between.m:CUSTOMARG=the input for this action is the scalar output from one or more other actions.dFUNC=0.5*step(0.5-x)+x*step(x-0.5)compulsory keywordthe function you wish to evaluatePERIODIC=NO # check the function you are applying: PRINTcompulsory keywordif the output of your function is periodic then you should specify the periodicity of the function.ARG=the input for this action is the scalar output from one or more other actions.d,mFILE=checkme RESTRAINTthe name of the file on which to output these quantitiesARG=the input for this action is the scalar output from one or more other actions.dAT=0.5compulsory keywordthe position of the restraintKAPPA=10.0compulsory keyword ( default=0.0 )specifies that the restraint is harmonic and what the values of the force constants on each of the variables are

(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

# take center of atoms 1 to 10 as reference point 1PRINT ARG=onaxis,fromaxisp1:CENTERATOMS=1-10 # take center of atoms 11 to 20 as reference point 2the list of atoms which are involved the virtual atom's definition.p2:CENTERATOMS=11-20 # take center of atoms 21 to 30 as reference point 3the list of atoms which are involved the virtual atom's definition.p3:CENTERATOMS=21-30 # compute distancesthe list of atoms which are involved the virtual atom's definition.d12:DISTANCEATOMS=the pair of atom that we are calculating the distance between.p1,p2d13:DISTANCEATOMS=the pair of atom that we are calculating the distance between.p1,p3d23:DISTANCEATOMS=the pair of atom that we are calculating the distance between.p2,p3# compute progress variable of the projection of point p3 # along the vector joining p1 and p2 # notice that progress is measured from the middle pointonaxis:CUSTOMARG=the input for this action is the scalar output from one or more other actions.d13,d23,d12FUNC=(0.5*(y^2-x^2)/z)compulsory keywordthe function you wish to evaluatecompulsory keywordif the output of your function is periodic then you should specify the periodicity of the function.fromaxis:CUSTOMARG=the input for this action is the scalar output from one or more other actions.d13,d23,d12,onaxisVAR=x,y,z,othe names to give each of the arguments in the function.FUNC=(0.5*(y^2+x^2)-o^2-0.25*z^2)compulsory keywordthe function you wish to evaluatecompulsory keywordif the output of your function is periodic then you should specify the periodicity of the function.

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 [103].

- Glossary of keywords and components

- 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

NUMERICAL_DERIVATIVES | ( default=off ) calculate the derivatives for these quantities numerically |

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... |

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. |