Shortcut: CUSTOM
| Module | function |
|---|---|
| Description | Usage |
| Calculate a combination of variables using a custom expression. |   |
| output value | type |
| an arbitrary function | scalar/vector/matrix/grid |
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/vector/matrix/grid | the values input to this function |
Further details and examples
Calculate a combination of variables using a custom expression.
CUSTOM is one of the most useful actions in PLUMED. This action takes in a list of arguments and then uses the lepton mathematical expression parser to evaluate a user defined function of these input arguments. We can thus use this action in the input below to perform a metadynamics simulation using the difference between two distances as a CV.
 |
dAB: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=10,12 dAC: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=10,15 diff: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=dAB,dAC FUNCthe function you wish to evaluate=y-x PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO # notice: the previous line could be replaced with the following # diff: COMBINE ARG=dAB,dAC COEFFICIENTS=-1,1 METADUsed to performed metadynamics on one or more collective variables. More details ARGthe labels of the scalars on which the bias will act=diff SIGMAthe widths of the Gaussian hills=0.1 HEIGHTthe heights of the Gaussian hills=0.5 BIASFACTORuse well tempered metadynamics and use this bias factor=10 PACEthe frequency for hill addition=100
The particular function that should be evaluated from the input arguments is specified using the FUNC keyword.
The function provided to the FUNC keyword is written in terms of x and y in the input above. x here deonetes the
first argument provided to the ARG keyword, dAB, while y is the second argument provided to the ARG keyword, dAC.
The VAR keyword
If you wish, you can rewrite the example input above more transparantly as:
|
dAB: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=10,12 dAC: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=10,15 diff: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=dAB,dAC VARthe names to give each of the arguments in the function=dAB,dAC FUNCthe function you wish to evaluate=dAC-dAB PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO METADUsed to performed metadynamics on one or more collective variables. More details ARGthe labels of the scalars on which the bias will act=diff SIGMAthe widths of the Gaussian hills=0.1 HEIGHTthe heights of the Gaussian hills=0.5 BIASFACTORuse well tempered metadynamics and use this bias factor=10 PACEthe frequency for hill addition=100
By using the VAR keyword here we ensure that we can use the labels of the arguments in the mathematical expression that
we provide to the FUNC argument. Notice that, if you have four or more arguments you must use the VAR keyword. With
three or less arguments the VAR keyword can be ommitted and the symbols x, y and z can be used to denote the first,
second and third arguments respectively.
The following input illustrates a case where using the VAR keyword is essential. This input tells PLUMED to
print the angle between the vector connecting atoms 1,2 and the vector connecting atoms 2,3.
|
d1: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 COMPONENTS calculate the x, y and z components of the distance separately and store them as label d2: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=2,3 COMPONENTS calculate the x, y and z components of the distance separately and store them as label theta: CUSTOMCalculate a combination of variables using a custom expression. More details ... ARGthe values input to this function=d1.x,d1.y,d1.z,d2.x,d2.y,d2.z VARthe names to give each of the arguments in the function=ax,ay,az,bx,by,bz FUNCthe 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))) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO ...
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=theta
Functions and constants
The previous examples demonstrates how CUSTOM can be used to evaluate mathematical expressions that involve taking powers (^), adding (+),
multiplying (*), dividing (/) and subtracting (-) variables and can control the order in which operations are performed by using parenthesis.
In addition to these basic binary operations you can also use a range of mathematical functions in your expressions. The following table lists all the mathematical functions
that you can use in in the input to the FUNC keyword for CUSTOM.
| Function | Description |
|---|---|
| sqrt(x) | The square root of x |
| exp(x) | The exponential of x i.e. ex |
| log(x) | The natural logarithm of x |
| sin(x) | The sine of x |
| cos(x) | The cosine of x |
| sec(x) | The reciprocal of the cosine of x. 1cos(x) |
| csc(x) | The reciprocal of the sine of x. 1sin(x) |
| tan(x) | The tangent of x i.e. sin(x)cos(x) |
| cot(x) | The reciprocal of the tangent of x. 1tan(x) |
| asin(x) | The principal arc sine of x. Returns −π2≤y≤π2 which gives x=sin(y) |
| acos(x) | The principal arc cosine of x. Returns 0≤y≤π which gives x=cos(y) |
| atan(x) | The principal arc tangent of x. Returns −π2≤y≤π2 which gives x=tan(y) |
| atan2(x,y) | The principal arg tangent of xy. Returns −π≤z≤π which gives xy=tan(z) |
| sinh(x) | The hyperbolic sine of x |
| cosh(x) | the hyperbolic cosine of x |
| tanh(x) | The hyperbolic tangent of x |
| erf(x) | The error function 2√π∫x0e−t2dt |
| erfc(x) | The complementary error function 1−2√π∫x0e−t2dt |
| step(x) | 1 if x≥0 and 0 otherwise |
| delta(x) | inf if x=0 and 0 otherwise |
| nandelta(x) | nan if x=0 and 0 otherwise |
| square(x) | The square of x i.e. x2 |
| cube(x) | The cube of x i.e. x3 |
| recip(x) | The reciprocal of x i.e. 1x |
| min(x,y) | If x<y this function returns x. If y≤x this function returns y |
| max(x,y) | If x>y this function returns x. If y≥x this function returns y |
| abs(x) | The absolute value of x |
| floor(x) | The largest integer that is less than x |
| ceil(x) | The smallest integer that is greater than x |
| select(x,y,z) | If x==0 this returns z otherwise this returns y |
| acot(x) | Returns the value of −π2≤y≤π2 which gives 1x=tan(y) |
| asec(x) | Returns the value of 0≤y≤π which gives 1x=cos(y) |
| acsc(x) | Returns the value of −π2≤y≤π2 which gives 1x=sin(y) |
| coth(x) | The recipricoal of the hyperbolic tangent of x. 1tanh(x) |
| sech(x) | The recipricoal of the hyperbolic cosine of x. 1cosh(x) |
| csch(x) | The recipricoal of the hyperbolic sine of x. 1sinh(x) |
| asinh(x) | The nonnegative area hyperbolic sine of x. Returns y which gives x=sinh(y) |
| acosh(x) | The nonnegative area hyperbolic cosine of x. Returns 0≤y≤∞ which gives x=cosh(y) |
| atanh(x) | The nonnegative area hyperbolic tangent of −1≤x≤1. Returns y which gives x=tanh(y). |
| acoth(x) | The inverse hyperbolic tangent of x is calculated as 12ln(x+1x−1) |
| asech(x) | The inverse hyperbolic secant of x is calculated as log(√1x−1√1x+1+1x) |
| acsch(x) | The inverse hyperbolic cosecant of x is calculated as log(1x+√1x2+1) |
Notice, that you can also incorporate the following constants in the expressions that are used in the input to FUNC:
| Symbol | Description |
|---|---|
e |
Euler's number - the base for the natural logarithm |
log2e |
1/log(2) |
log10e |
1/log(10) |
ln2 |
log(2) |
ln10 |
log(10) |
pi |
the circle constant π |
pi_2 |
π/2 |
pi_4 |
π/4 |
| `sqrt2 | √(2) |
sqrt1_2 |
√(0.5) |
The way one of these constants can be used in an expression is illustrated in the following example:
|
d: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 # This function is evaluating the area of the circle whose radius is # given by the distance between atoms 1 and 2. c: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d FUNCthe function you wish to evaluate=pi*x*x PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=c FILEthe name of the file on which to output these quantities=colvar
The step function
The step operation (that is the Heaviside function) from the table above allow you to use if clauses in CUSTOM actions.
As discussed in the table step(x) is 1 when x is positive and 0 when x is negative. So the function step(1-x) is
1 if x is less than one and zero otherwise.
Using the step operation multiple times in a function allows you to perform logical operations. For example, the equivalent of the AND operator
is the product so, for example, step(1.0-x)*step(x-0.5) is only equal to 1 when x is greater than 0.5 AND less than 1.0.
By a similar logic we can use the function 1-step(1.0-x)*step(x-0.5) to create a value that is 1 if x is less than 0.5 OR
greater than 1.0.
The example below illustrtes how we can put these ideas of using the step operation into practise.
|
d: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=10,15 m: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d FUNCthe function you wish to evaluate=0.5*step(0.5-x)+x*step(x-0.5) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO # check the function you are applying: PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=d,m FILEthe name of the file on which to output these quantities=checkme RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=d ATthe position of the restraint=0.5 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=10.0
The meaning of the function 0.5*step(0.5-x)+x*step(x-0.5) in this example 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 result can be achieved by using UPPER_WALLS
However, with CUSTOM you can create much more complex definitions.
Notice that we can apply a force on the value m by using the RESTRAINT command as the function we defined in the expression that was passed to the FUNC keyword is continuous.
In general, however, you must be careful when using the step, delta, nandelta and select functions as you can easily write expression for
discontinuous functions by using these operations. If you want to check if a function you have created using step
is continuous you can easily plot the function in gnuplot by using a commands like those shown below
# 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)
Using TIME as a variable
Notice that you can use CUSTOM to implement a MOVINGRESTRAINT as shown below.
|
t: TIMEretrieve the time of the simulation to be used elsewhere More details d: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 f: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d,t FUNCthe function you wish to evaluate=100*(x-((0.2-0.1)*y/100))^2 PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO BIASVALUETakes the value of one variable and use it as a bias More details ARGthe labels of the scalar/vector arguments whose values will be used as a bias on the system=f
In a 100~ps simulation that was run with this input the distance beetween atom 1 and 2 would be forced to increase from 0.1 to 0.2 nm.
Using CUSTOM in shortcuts
The CUSTOM action is used in many of the shortcut actions that are implemented in PLUMED. We think that using this action in these places is beneficial as it ensures that the mathematical expressions that are used in the method are visible in the log. We have found that there are many actions that are used in relatively few papers. When implementing these actions we think that sharing implementations of these methods that are comprehensible is more important than sharing methods that are fast.
As an example of why this is useful consider some of the variants of the DISTANCE keyword that were present in PLUMED 1.3. These variants allowed you to compute the distance between a point and a line defined by two other points or the progression along that line. In PLUMED 2.10 we can implement these variables using the following input file:
|
# take center of atoms 1 to 10 as reference point 1 p1: CENTERCalculate the center for a group of atoms, with arbitrary weights. More details ATOMSthe group of atoms that you are calculating the Gyration Tensor for=1-10 # take center of atoms 11 to 20 as reference point 2 p2: CENTERCalculate the center for a group of atoms, with arbitrary weights. More details ATOMSthe group of atoms that you are calculating the Gyration Tensor for=11-20 # take center of atoms 21 to 30 as reference point 3 p3: CENTERCalculate the center for a group of atoms, with arbitrary weights. More details ATOMSthe group of atoms that you are calculating the Gyration Tensor for=21-30 # compute distances d12: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=p1,p2 d13: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=p1,p3 d23: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe 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 point onaxis: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d13,d23,d12 FUNCthe function you wish to evaluate=(0.5*(y^2-x^2)/z) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO # compute between point p3 and the vector joining p1 and p2 fromaxis: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d13,d23,d12,onaxis VARthe names to give each of the arguments in the function=x,y,z,o FUNCthe function you wish to evaluate=(0.5*(y^2+x^2)-o^2-0.25*z^2) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=onaxis,fromaxis
The equations in this input were also used to combine RMSD values from different snapshots of a protein so as to define progression (S) and distance (Z) variables in the paper that is cited in the bibliography. We can understand how these expressions are derived by noting that x, y and z are the distances between atoms 1 and 3, 2 and 3 and 1 and 2 respectively. The projection of the vector connecting atom 1 to atom 3 onto the vector connecting atom 1 to atom 2 is thus xcos(θ), where theta is the angle between the vector connecting atoms 1 and 3 and the vector connecting atoms 1 and 2. We can arrive at the following expression for xcos(θ) by rearranging the cosine rule:
xcos(θ)=y2−x2z−z2
Notice that the value called onaxis in the above input is thus o=xcos(θ)+z2. Adding the factor of z2 ensures that the origin
is at the center of the bond connecting atom 1 to atom 2.
The value fromaxis measures the square of the distance from the the line. It is calculated using pythagoras theorem as follows:
f2=y2−x2cos2(θ)
Inserting xcos(θ)=o−z2 into this expression gives:
f2=y2−(o−z2)2=y2−o2+oz−z24
Inserting the fact that oz=y2−x22, which comes from the expression for o that was used to calculate onaxis, gets us to the expression that is used to calculate fromaxis.
CUSTOM with vector arguments
The examples above have shown how CUSTOM operates when the input arguments are scalars. You can also pass vectors in the argument to a CUSTOM action. The function you define will then
be applied to each element of the vector in turn. So, for example in the input below a vector that contains three angles is passed to the CUSTOM action. The CUSTOM action calculates the
cosine of these three angles and outputs them in a three dimensional vector called c that is printed to the colvar file.
|
a: ANGLECalculate one or multiple angle/s. More details ATOMS1the list of atoms involved in this collective variable (either 3 or 4 atoms)=1,2,3 ATOMS2the list of atoms involved in this collective variable (either 3 or 4 atoms)=4,5,6 ATOMS3the list of atoms involved in this collective variable (either 3 or 4 atoms)=7,8,9 c: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=a FUNCthe function you wish to evaluate=cos(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=c FILEthe name of the file on which to output these quantities=colvar
You are not confined to passing a single vector to CUSTOM. The input below shows what you can do by pass two vectors with the same numbers of elements. The first element of the vector output by the CUSTOM action here contains the projection of the vector connecting atom 1 and 2 on the vector connecting atom 2 and 3, the second element contains the projection of the vector connecting atoms 4 and 5 on the vector connecting atoms 5 and 6 and the final element contains the projection of the vector connecting atoms 7 and 8 on the vector connecting atoms 8 and 9.
|
d: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=4,5 ATOMS3the pair of atom that we are calculating the distance between=7,8 a: ANGLECalculate one or multiple angle/s. More details ATOMS1the list of atoms involved in this collective variable (either 3 or 4 atoms)=1,2,3 ATOMS2the list of atoms involved in this collective variable (either 3 or 4 atoms)=4,5,6 ATOMS3the list of atoms involved in this collective variable (either 3 or 4 atoms)=7,8,9 c: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d,a FUNCthe function you wish to evaluate=x*cos(y) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=c FILEthe name of the file on which to output these quantities=colvar
Notice, when we multiply two vectors in CUSTOM the output is a vector. This product that emerges from using a CUSTOM action is not the scalar or cross product of the input vectors.
Lastly, notice that you can pass a mixture of scalars and vectors in the input to a CUSTOM action as shown below.
|
d: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 a: ANGLECalculate one or multiple angle/s. More details ATOMS1the list of atoms involved in this collective variable (either 3 or 4 atoms)=1,2,3 ATOMS2the list of atoms involved in this collective variable (either 3 or 4 atoms)=1,2,4 ATOMS3the list of atoms involved in this collective variable (either 3 or 4 atoms)=1,2,5 ATOMS4the list of atoms involved in this collective variable (either 3 or 4 atoms)=1,2,6 c: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d,a FUNCthe function you wish to evaluate=x*cos(y) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=c FILEthe name of the file on which to output these quantities=colvar
The multiplication of a scalar by a vector in the above input is done in the usual way.
Similarly, dividing a vector by a scalar is equivalent to multiplying the vector by the reciprocal of the scalar. If you write an expression that adds or subtract a
scalar from a vector addition is performed. To understand why consider the following example that adds the constant c to the input vector of distances d. The
result of this operation is a vector f that contains the three input distances from d with 23 added to each of them.
|
c: CONSTANTCreate a constant value that can be passed to actions This action has hidden defaults. More details VALUEthe single number that you would like to store=23 d: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=4,5 ATOMS3the pair of atom that we are calculating the distance between=7,8 f: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d,c 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 PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=f FILEthe name of the file on which to output these quantities=colvar
CUSTOM with matrix arguments
You can also pass matrices in the argument to a CUSTOM action. These input matrices are treated similarly to input vectors. In other words, any function you define is applied to each element of the matrix in turn so if the input matrix is N×MtheoutputmatrixisalsoN \times M$. The following example illustrates how you can use this functionality to calculate all the angles between a set of bond vectors.
|
# Calculate the vectors connecting four atoms d: DISTANCECalculate the distance/s between pairs of atoms. More details COMPONENTS calculate the x, y and z components of the distance separately and store them as label ATOMS1the pair of atom that we are calculating the distance between=1,2 ATOMS2the pair of atom that we are calculating the distance between=3,4 ATOMS3the pair of atom that we are calculating the distance between=5,6 ATOMS4the pair of atom that we are calculating the distance between=7,8 # Calculate the norm of these four vectors norm: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d.x,d.y,d.z FUNCthe function you wish to evaluate=sqrt(x*x+y*y+z*z) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO # Now calculate the directors of the vectors norm_x: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d.x,norm 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 norm_y: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d.y,norm 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 norm_z: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=d.z,norm 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 # And combine all these directors in a matrix stack: VSTACKCreate a matrix by stacking vectors together More details ARGthe values that you would like to stack together to construct the output matrix=norm_x,norm_y,norm_z # Now calculate the matrix of dot products between directors (these are the cosines of the angles) stackT: TRANSPOSECalculate the transpose of a matrix More details ARGthe label of the vector or matrix that should be transposed=stack cosa: MATRIX_PRODUCTCalculate the product of two matrices More details ARGthe label of the two matrices from which the product is calculated=stack,stackT # And finally get the 4x4 matrix of angles and print it to a file angles: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=cosa FUNCthe function you wish to evaluate=acos(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=angles FILEthe name of the file on which to output these quantities=colvar
Notice that you can pass multiple N×M matrices in the input to a CUSTOM action as illustrated in the example below:
|
c1: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=2,3,4,5 NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2 c2: CONSTANTCreate a constant value that can be passed to actions More details VALUESthe numbers that are in your constant value=1,0,0,1 NROWS the number of rows in your input matrix=2 NCOLS the number of columns in your matrix=2 f: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=c1,c2 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 PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=f FILEthe name of the file on which to output these quantities=colvar
The four by four matrix that is calculated by the custom action in this input is given by:
f=(2005)
which is the element-wise Hadamard product and not the matrix product.
By a similar token if you have a custom command that takes two matrices in input and use FUNC=x/y the Hadamard product between the matrix
x and a matrix that contains the reciprocals of each of the elements in y is computed. If you wish to calcalculate the
product of two matrices you should use the MATRIX_PRODUCT comamnd.
Similarly, if you want to calculate the product of a matrix and a vector you should use the MATRIX_VECTOR_PRODUCT
command.
Lastly, note that you can pass a mixture of scalars and N×M matrices in the input to a CUSTOM command. As with vectors, you can think of any scalars you pass as being converted into N×M matrix in which every element is equal to the input scalar.
CUSTOM with grid arguments
CUSTOM will also accept a function on a grid in input. You might use this feature if you want to calculate a free energy from a histogram using F(s)=−kBTlog[H(s)] as illustrated in the input below:
|
x: DISTANCECalculate the distance/s between pairs of atoms. More details ATOMSthe pair of atom that we are calculating the distance between=1,2 hA: HISTOGRAMAccumulate the average probability density along a few CVs from a trajectory. This action is a shortcut and it has hidden defaults. More details ARGthe quantities that are being used to construct the histogram=x GRID_MIN the lower bounds for the grid=0.0 GRID_MAX the upper bounds for the grid=3.0 GRID_BINthe number of bins for the grid=100 BANDWIDTHthe bandwidths for kernel density esimtation=0.1 fE: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=hA FUNCthe function you wish to evaluate=-2.5*log(x) PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO DUMPGRIDOutput the function on the grid to a file with the PLUMED grid format. More details ARGthe label for the grid that you would like to output=fE FILE the file on which to write the grid=fes.dat
Another way that this functonality is routinely used in PLUMED is in calculating the density field for a symmetry function. The example below shows how you would do this in practise. The final output here is a function on a grid that tells you the average value of the FCC order parameter at each point in the cell.
|
# Evaluate the FCC order parameter for all of the atoms fcc: FCCUBICMeasure how similar the environment around atoms is to that found in a FCC structure. This action is a shortcut and it has hidden defaults. More details SPECIESthe list of atoms for which the symmetry function is being calculated and the atoms that can be in the environments=1-5184 SWITCHthe switching function that it used in the construction of the contact matrix. Options for this keyword are explained in the documentation for LESS_THAN.={CUBIC D_0=1.2 D_MAX=1.5} ALPHA The alpha parameter of the angular function that is used for FCCUBIC=27 # Calculate the distance between each atom and the origin on atom 1 dens_dist: DISTANCESCalculate the distances between multiple piars of atoms This action is a shortcut. More details ORIGINcalculate the distance of all the atoms specified using the ATOMS keyword from this point=1 ATOMSthe pairs of atoms that you would like to calculate the angles for=fcc COMPONENTS calculate the x, y and z components of the distance separately and store them as label # Do a KDE using the FCC order parameters for the weights of each gaussian and the positions of the atoms as the centers dens_numer: KDECreate a histogram from the input scalar/vector/matrix using KDE This action has hidden defaults. More details HEIGHTSthis keyword takes the label of an action that calculates a vector of values=fcc_n ARGthe label for the value that should be used to construct the histogram=dens_dist.x,dens_dist.y,dens_dist.z GRID_BINthe number of bins for the grid=14,14,28 BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0 # Estimate the density of atoms at each point in the box ones: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details SIZEthe number of ones that you would like to create=5184 dens_denom: KDECreate a histogram from the input scalar/vector/matrix using KDE This action has hidden defaults. More details ARGthe label for the value that should be used to construct the histogram=dens_dist.x,dens_dist.y,dens_dist.z GRID_BINthe number of bins for the grid=14,14,28 HEIGHTSthis keyword takes the label of an action that calculates a vector of values=ones BANDWIDTHthe bandwidths for kernel density esimtation=1.0,1.0,1.0 # Now calculate the average value of the order parameter at each point in the box dens: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=dens_numer,dens_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 DUMPCUBEOutput a three dimensional grid using the Gaussian cube file format. More details ARGthe label for the grid that you would like to output=dens FILE the file on which to write the grid=dens.cube FMTthe format that should be used to output real numbers=%8.4f
References
More information about how this action can be used is available in the following articles: - A. Pérez-Villa, M. Darvas, G. Bussi, ATP dependent NS3 helicase interaction with RNA: insights from molecular simulations. Nucleic Acids Research. 43, 8725–8734 (2015)
Syntax
The following table describes the keywords and options that can be used with this action
| Keyword | Type | Default | Description |
|---|---|---|---|
| ARG | input | none | the values input to this function |
| PERIODIC | compulsory | none | if the output of your function is periodic then you should specify the periodicity of the function |
| FUNC | compulsory | none | the function you wish to evaluate |
| VAR | optional | not used | the names to give each of the arguments in the function |