From 6ca0ab68ac45e322aec53057b6a4cf01b1a6dd7b Mon Sep 17 00:00:00 2001 From: Gareth Aneurin Tribello Date: Fri, 22 Nov 2024 14:51:40 +0000 Subject: [PATCH] Added new style documentation for everything in function --- new-manual/parsing.md | 6 +- src/function/Between.cpp | 126 +++++--- src/function/Combine.cpp | 128 ++++++-- src/function/Custom.cpp | 387 +++++++++++++++++++----- src/function/Ensemble.cpp | 9 +- src/function/FuncPathGeneral.cpp | 19 +- src/function/FuncPathMSD.cpp | 74 ++--- src/function/FuncSumHills.cpp | 2 +- src/function/Highest.cpp | 138 ++++++++- src/function/LessThan.cpp | 490 ++++++++++++++++++++++--------- src/function/LocalEnsemble.cpp | 9 +- src/function/Moments.cpp | 34 ++- src/function/MoreThan.cpp | 65 +++- src/function/Piecewise.cpp | 59 ++-- src/function/Product.cpp | 16 +- src/function/Sort.cpp | 29 +- src/function/Stats.cpp | 6 +- src/function/Sum.cpp | 41 ++- src/generic/Constant.cpp | 11 + 19 files changed, 1258 insertions(+), 391 deletions(-) diff --git a/new-manual/parsing.md b/new-manual/parsing.md index 206d7b71a7..9cf1a252ee 100644 --- a/new-manual/parsing.md +++ b/new-manual/parsing.md @@ -27,8 +27,8 @@ t: METAD ARG=e1 SIGMA=0.15 PACE=10 HEIGHT=2 GRID_MIN=-pi GRID_MAX=pi GRID_BIN=20 Notice here that the boundaries for `GRID_MIN` and `GRID_MAX` are `-pi` and `pi`. -Any real numbers that are read in from input are interpretted using the [Lepton library](Custom.md) so you can thus employ -complicated expressions such as `1+2` or `exp(10)` as shown in the in the input as shown below: +Any real numbers that are read in from input are interpretted using the [Lepton library] that is described in the documtation for the [CUSTOM](CUSTOM.md) +action. You can thus employ complicated expressions such as `1+2` or `exp(10)` as shown in the in the input as shown below: ```plumed #SETTINGS MOLFILE=regtest/basic/rt65/AA.pdb @@ -37,7 +37,7 @@ e1: TORSION ATOMS=@epsilon-1 RESTRAINT ARG=e1 AT=1+0.5 ``` -The lepton library is able to interpret any of thse following constants: +You can also also write expressions in terms of any of the following constants: | Symbol | Description | | :----- |:------------| diff --git a/src/function/Between.cpp b/src/function/Between.cpp index ae3dfe9a43..e06c347807 100644 --- a/src/function/Between.cpp +++ b/src/function/Between.cpp @@ -34,58 +34,106 @@ namespace function { /* Use a switching function to determine how many of the input variables are within a certain range. -If we have multiple instances of a variable we can estimate the probability density function -for that variable using a process called kernel density estimation: +This action takes one argument, $s$ and evaluates the following function: -\f[ -P(s) = \sum_i K\left( \frac{s - s_i}{w} \right) -\f] +$$ +w(s) = \int_a^b K\left( \frac{x - s}{\sigma} \right) \textrm{d}x +$$ -In this equation \f$K\f$ is a symmetric function that must integrate to one that is often -called a kernel function and \f$w\f$ is a smearing parameter. From a probability density function calculated using -kernel density estimation we can calculate the number/fraction of values between an upper and lower -bound using: +In this equation $K$ is a symmetric function that must integrate to one and that is often +called a [kernel function](https://en.wikipedia.org/wiki/Kernel_(statistics)) and $\sigma$ is a smearing parameter. +The above function can be used to evaluate whether $s$ is between $a$ and $b$. The advantage of using the function above is that +the resulting quantity has continuous derivatives. It can thus be used when calculating a collective variable upon which a simulation +bias will be applied. -\f[ -w(s) = \int_a^b \sum_i K\left( \frac{s - s_i}{w} \right) -\f] +The following example, shows how we can apply the function above on the instantaneous value of the distance between atom 1 and 2. +The BETWEEN action here is used to determine whether the input distance is between 0.1 and 0.2 nm. -All the input to calculate a quantity like \f$w(s)\f$ is generally provided through a single -keyword that will have the following form: +```plumed +d: DISTANCE ATOMS=1,2 +b: BETWEEN ARG=d SWITCH={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5} +``` -KEYWORD={TYPE UPPER=\f$a\f$ LOWER=\f$b\f$ SMEAR=\f$\frac{w}{b-a}\f$} +## The Kernel function -This will calculate the number of values between \f$a\f$ and \f$b\f$. To calculate -the fraction of values you add the word NORM to the input specification. If the -function keyword SMEAR is not present \f$w\f$ is set equal to \f$0.5(b-a)\f$. Finally, -type should specify one of the kernel types that is present in plumed. These are listed -in the table below: +The $\sigma$ values in the expressions above is calculated from the parameters $a$, $b$ and $s$ that are provided using the +`LOWER`, `UPPER` and `SMEAR` parameters respectively using the following function: - - - - - - - - -
TYPE FUNCTION
GAUSSIAN \f$\frac{1}{\sqrt{2\pi}w} \exp\left( -\frac{(s-s_i)^2}{2w^2} \right)\f$
TRIANGULAR \f$ \frac{1}{2w} \left( 1. - \left| \frac{s-s_i}{w} \right| \right) \quad \frac{s-s_i}{w}<1 \f$
+$$ +\sigma = s(b-a) +$$ -Some keywords can also be used to calculate a discrete version of the histogram. That -is to say the number of values between \f$a\f$ and \f$b\f$, the number of values between -\f$b\f$ and \f$c\f$ and so on. A keyword that specifies this sort of calculation would look -something like +Also note that the Kernel function $K$ that is used in the first example is a Gaussian. The actual integral that is evaluated is thus: -KEYWORD={TYPE UPPER=\f$a\f$ LOWER=\f$b\f$ NBINS=\f$n\f$ SMEAR=\f$\frac{w}{n(b-a)}\f$} +$$ +w(s) = \frac{1}{\sqrt{2\pi}\sigma} \int_a^b \exp\left( -\frac{(x-s)^2}{2\sigma^2} \textrm{d}x +$$ -This specification would calculate the following vector of quantities: +The Gaussian kernel in this expression can be replaced by a triangular Kernel by changing the input to: -\f[ -w_j(s) = \int_{a + \frac{j-1}{n}(b-a)}^{a + \frac{j}{n}(b-a)} \sum_i K\left( \frac{s - s_i}{w} \right) -\f] +```plumed +d: DISTANCE ATOMS=1,2 +b: BETWEEN ARG=d SWITCH={TRIANGULAR LOWER=0.1 UPPER=0.2 SMEAR=0.5} +``` +With this input the integral is then evaluated using: -\par Examples +$$ +w(s) = \frac{1}{2\sigma} \int_a^b 1 - H\left( \frac{x-s}{\sigma} \right) \textrm{d}x +$$ + +where: + +$$ +H(x) = \begin{cases} +x & \textrm{if} \quad x<1 \\ +0 & \textrm{otherwise} +\end{cases} +$$ + +## Non rank zero arguments + +Instead of passing a single scalar in the input to the `BETWEEN` action you can pass a single vector as shown here: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +b: BETWEEN ARG=d SWITCH={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5} +``` + +The input to the `BETWEEN` action here is a vector with four elements. The output from the action `b` is similarly +a vector with four elements. In calculating the elements of this vector PLUMED applies the function described in the previous +section on each of the distances in turn. The first element of `b` thus tells you if the distance between atoms 1 and 2 is between +0.1 and 0.2 nm, the second element tells you if the distance between atoms 3 and 4 is between 0.1 and 0.2 nm and so on. + +You can use the commands in the above example input to evaluate the number of distances that are within the range of interest as follows: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +b: BETWEEN ARG=d SWITCH={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5} +s: SUM ARG=b PERIODIC=NO +PRINT ARG=s FILE=colvar +``` + +The final scalar that is output here is evaluated using the following summation: + +$$ +s = \sum_i \int_a^b \left( \frac{x - d_i}{\sigma} \right) \textrm{d}x +$$ + +where the sum over $i$ here runs over the four distances in the above expression. This scalar tells you the number of distances that are +between 0.1 and 0.2. + +Notice that you can do something similar with a matrix as input as shown below: + +```plumed +d: DISTANCE_MATRIX GROUPA=1-10 GROUPB=11-20 +b: BETWEEN ARG=d SWITCH={GAUSSIAN LOWER=0.1 UPPER=0.2 SMEAR=0.5} +s: SUM ARG=b PERIODIC=NO +PRINT ARG=s FILE=colvar +``` + +This input tells PLUMED to calculate the 100 distances between the atoms in the two input groups. The final value that is printed to the colvar file then +tells you how many of these distances are between 0.1 and 0.2 nm. */ //+ENDPLUMEDOC diff --git a/src/function/Combine.cpp b/src/function/Combine.cpp index fef7f4e5ae..500d692ba6 100644 --- a/src/function/Combine.cpp +++ b/src/function/Combine.cpp @@ -34,45 +34,119 @@ namespace function { /* Calculate a polynomial combination of a set of other variables. -The functional form of this function is +This action takes in $N_{arg}$ arguments ($x_i$) and computes the following function of them: + \f[ C=\sum_{i=1}^{N_{arg}} c_i (x_i-a_i)^{p_i} \f] -The coefficients c, the parameters a and the powers p are provided as vectors. +The $c_i$, $a_i$ and $p_i$ values in this expression are provided through the COEFFICIENTS, PARAMETERS and POWERS keywords respectively. +The following example illustrates how this action can be used to calculate and print the square of the distance between atom 1 and atom 2. -Notice that COMBINE is not able to predict which will be periodic domain -of the computed value automatically. The user is thus forced to specify it -explicitly. Use PERIODIC=NO if the resulting variable is not periodic, -and PERIODIC=A,B where A and B are the two boundaries if the resulting variable -is periodic. +```plumed +d: DISTANCE ATOMS=1,2 COMPONENTS +c: COMBINE ARG=d.x,d.y,d.z COEFFICIENTS=1,1,1 PARAMETERS=0,0,0 POWERS=2,2,2 PERIODIC=NO +PRINT ARG=c FILE=colvar +``` +Notice that if the COEFFICIENTS keyword is absent all the $c_i$ values are set equal to 1. +Furthermore, if the PARAMETERS keyword is absent all the $a_i$ values are set equal to 0. +We can thus make use of these defaults and rewrite the input above as: +```plumed +d: DISTANCE ATOMS=1,2 COMPONENTS +c: COMBINE ARG=d.x,d.y,d.z POWERS=2,2,2 PERIODIC=NO +PRINT ARG=c FILE=colvar +``` -\par Examples +Notice that we cannot remove the POWERS keyword here as if it is absent all the $p_i$ values are set equal to 1. + +## Periodic arguments -The following input tells plumed to print the distance between atoms 3 and 5 -its square (as computed from the x,y,z components) and the distance -again as computed from the square root of the square. -\plumedfile -DISTANCE LABEL=dist ATOMS=3,5 COMPONENTS -COMBINE LABEL=distance2 ARG=dist.x,dist.y,dist.z POWERS=2,2,2 PERIODIC=NO -COMBINE LABEL=distance ARG=distance2 POWERS=0.5 PERIODIC=NO -PRINT ARG=distance,distance2 -\endplumedfile -(See also \ref PRINT and \ref DISTANCE). - -The following input tells plumed to add a restraint on the -cube of a dihedral angle. Notice that since the angle has a -periodic domain --pi,pi its cube has a domain -pi**3,pi**3. -\plumedfile +The COMBINE action is not able to predict the periodic domain for the function that is computed from the arguments +automatically. The user is thus forced to specify it explicitly. Use PERIODIC=NO if the resulting variable is not periodic, +and PERIODIC=A,B where A and B are the two boundaries for the periodic domain if the resulting variable is periodic. +The following provides an example where the output from combine has a periodic domain. In this input we are taking the +cube of a dihedral angle. The dihedral angle has a periodic domain that runs from $-\pi$ to $\pi$. The cube of this variable +thus has a periodic domain that runs from $-\pi^3$ to $\pi^3$ as indicated in the following input. + +```plumed t: TORSION ATOMS=1,3,5,7 -c: COMBINE ARG=t POWERS=3 PERIODIC=-31.0062766802998,31.0062766802998 -RESTRAINT ARG=c KAPPA=10 AT=0 -\endplumedfile +#c: COMBINE ARG=t POWERS=3 PERIODIC=-31.0062766802998,31.0062766802998 +c: COMBINE ARG=t POWERS=3 PERIODIC=-pi^3,pi^3 +PRINT ARG=c FILE=colvar +``` + +## Vector arguments + +The two examples in the previous section demonstrate how to use the COMBINE action with scalar arguments. However, you can also +pass arguments to this action that have a rank greater than zero. For example, in the example below COMBINE accepts three +vectors with 4 elements in input: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 COMPONENTS +c: COMBINE ARG=d.x,d.y,d.z POWERS=2,2,2 PERIODIC=NO +PRINT ARG=c FILE=colvar +``` + +The output from the COMBINE action here is also a vector with four elements. The first element of this vector is the square of the +distance betwen atoms 1 and 2, the secton is the square of the distance between atoms 3 and 4 and so on. + +The COMBINE action can also take a mixture of scalars and vectors in input. The following input illustrates an +COMBINE action that takes vectors and scalars in input. + +```plumed +p: CONSTANT VALUE=2 +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +c: COMBINE ARG=d,p COEFFICIENTS=4,-1 POWERS=2.5,1 +PRINT ARG=c FILE=colvar +``` + +The elements of the vector that is calculated by the COMBINE action here are given by: + +$$ +c_i = 4d_i^{2.5} - 2 +$$ + +The $d_i$ in this expression are the distances that were calculated by the DISTANCE action. The 2 comes +from the scalar `p` that passed to the ARG action in input. As a single scalar is passed the same number is +used when calculating all 4 elements of the output vector. In other words, the scalar behaves as if it is a +vector with four components that all have the same value. + +Lastly, notice that if you pass a single vector in input to COMBINE as in the following example, the output is still a vector: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +c: COMBINE ARG=d COEFFICIENTS=4 POWERS=2.5 PARAMETERS=0.5 +PRINT ARG=c FILE=colvar +``` + +To calculate the 4-dimensional output by the COMBINE action here we subtract 0.5 from each of the input distances, raise +the result from this subtraction to the power 2.5 and then multiply the result by 4. + +If you want to calculate a linear combination of the elements of a vector using the formula at the top of the page you should use +the [CUSTOM](CUSTOM.md) action to transform all the components of the input vector. You can then add all the results from these +transformations together using [SUM](SUM.md). + +## Matrix arguments + +You can also use matrices in the input to the COMBINE action as illustrated below: + +```plumed +d: DISTANCE_MATRIX GROUPA=1,2 GROUPB=3,4,5 COMPONENTS +c: COMBINE ARG=d.x,d.y,d.z POWERS=2,2,2 PERIODIC=NO +PRINT ARG=c FILE=colvar +``` + +The input to the combine action here consists of three $2\times3$ matrices. The output is thus a $2\times3$ matrix that contains the squares of the +distances between the atoms in GROUPA and the atoms in GROUPB. Notice that all the input matrices must have the same size as the elements of the final +matrix are calculated by applying the formula in the first section of this input to each set of elements to the input matrices in turn. +The input to this action can be a combination of matrices and scalars. If your input arguments are an $N\times M$ matrix and a scalar the scalar is treated as if +it is a $N\times M$ matrix which has all its elements equal to the input scalar. You __cannot__ use a mixture of vectors and matrices in the input to this action. +Furthermore, if you pass a single matrix to COMBINE the output is a matrix. To calculate a linear combination of all the elements in a matrix using the formula at the top of the page you should use +the [CUSTOM](CUSTOM.md) action to transform all the components of the input vector. You can then add all the results from these transformations together using [SUM](SUM.md). */ //+ENDPLUMEDOC diff --git a/src/function/Custom.cpp b/src/function/Custom.cpp index cd86f6c33d..367f24cc00 100644 --- a/src/function/Custom.cpp +++ b/src/function/Custom.cpp @@ -35,102 +35,196 @@ namespace function { /* 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). +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](https://simtk.org/projects/lepton) 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. -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 \subpage TIME action. - -\par Examples - -The following input tells plumed to perform a metadynamics -using as a CV the difference between two distances. -\plumedfile +```plumed dAB: DISTANCE ATOMS=10,12 dAC: DISTANCE ATOMS=10,15 diff: CUSTOM ARG=dAB,dAC FUNC=y-x PERIODIC=NO # notice: the previous line could be replaced with the following # diff: COMBINE ARG=dAB,dAC COEFFICIENTS=-1,1 METAD ARG=diff SIGMA=0.1 HEIGHT=0.5 BIASFACTOR=10 PACE=100 -\endplumedfile -(see also \ref DISTANCE, \ref COMBINE, and \ref 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 \ref 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. -\plumedfile -DISTANCE LABEL=d1 ATOMS=1,2 COMPONENTS -DISTANCE LABEL=d2 ATOMS=2,3 COMPONENTS -CUSTOM ... - LABEL=theta +``` + +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: + +```plumed +dAB: DISTANCE ATOMS=10,12 +dAC: DISTANCE ATOMS=10,15 +diff: CUSTOM ARG=dAB,dAC VAR=dAB,dAC FUNC=dAC-dAB PERIODIC=NO +METAD ARG=diff SIGMA=0.1 HEIGHT=0.5 BIASFACTOR=10 PACE=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. + +```plumed +d1: DISTANCE ATOMS=1,2 COMPONENTS +d2: DISTANCE ATOMS=2,3 COMPONENTS +theta: CUSTOM ... ARG=d1.x,d1.y,d1.z,d2.x,d2.y,d2.z VAR=ax,ay,az,bx,by,bz FUNC=acos((ax*bx+ay*by+az*bz)/sqrt((ax*ax+ay*ay+az*az)*(bx*bx+by*by+bz*bz))) PERIODIC=NO -... CUSTOM -PRINT ARG=theta -\endplumedfile -(See also \ref PRINT and \ref 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 -\plumedfile +PRINT ARG=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. $e^{x}$ | +| 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$. $\frac{1}{\cos(x)}$ | +| csc(x) | The reciprocal of the sine of $x$. $\frac{1}{\sin(x)}$ | +| tan(x) | The tangent of x i.e. $\frac{\sin(x)}(\cos(x)}$ | +| cot(x) | The reciprocal of the tangent of $x$. $\frac{1}{\tan(x)}$ | +| asin(x) | The principal arc sine of x. Returns $-\frac{\pi}{2} \le y \le \frac{\pi}{2}$ which gives $x = \sin(y)$ | +| acos(x) | The principal arc cosine of x. Returns $0 \le y \le \pi$ which gives $x=\cos(y)$ | +| atan(x) | The principal arc tangent of x. Returns $-\frac{\pi}{2} \le y \le \frac{\pi}{2}$ which gives $x = \tan(y)$ | +| atan2(x,y) | The principal arg tangent of $\frac{x}{y}$. Returns $-\pi \le z \le \pi$ which gives $\frac{x}{y} = \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](https://en.wikipedia.org/wiki/Error_function) $\frac{2}{\sqrt{\pi}}\int_0^x e^{-t^2} \txtrm{d}t$ | +| erfc(x) | The complementary error function $1-\frac{2}{\sqrt{\pi}}\int_0^x e^{-t^2} \txtrm{d}t$ | +| step(x) | 1 if $x \ge 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. $x^2$ | +| cube(x) | The cube of x i.e. $x^3$ | +| recip(x) | The reciprocal of x i.e. $\frac{1}{x}$ | +| min(x,y) | If $xy$ this function returns $x$. If $y\ge x$ this function returns $y$ | +| abs(x) | The absolute value of x i.e. $|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 $-\frac{\pi}{2} \le y \le \frac{\pi}{2}$ which gives $\frac{1}{x}=\tan(y)$ | +| asec(x) | Returns the value of $0 \le y \le \pi$ which gives $\frac{1}{x}=\cos(y)$ | +| acsc(x) | Returns the value of $-\frac{\pi}{2} \le y \le \frac{\pi}{2}$ which gives $\frac{1}{x}=\sin(y)$ | +| coth(x) | The recipricoal of the hyperbolic tangent of $x$. $\frac{1}{\tanh(x)}$ | +| sech(x) | The recipricoal of the hyperbolic cosine of $x$. $\frac{1}{\cosh(x)}$ | +| csch(x) | The recipricoal of the hyperbolic sine of $x$. $\frac{1}{\sinh(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\le y \le \infty$ which gives $x=\cosh(y)$ | +| atanh(x) | The nonnegative area hyperbolic tangent of $-1 \le x \le 1$. Returns $y$ which gives $x=\tanh(y)$. | +| acoth(x) | The inverse hyperbolic tangent of $x$ is calculated as $\frac{1}{2}\ln\left( \frac{x+1}{x-1} \right)$ | +| asech(x) | The inverse hyperbolic secant of $x$ is calculated as $\log\left( \sqrt{\frac{1}{x}-1}\sqrt{\frac{1}{x}+1} + \frac{1}{x}\right)$ | +| acsch(x) | The inverse hyperbolic cosecant of $x$ is calculated as $\log\left(\frac{1}{x}+\sqrt{\frac{1}{x^2}+1}\right)$ | + +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$ | +| `pi_2` | $\pi / 2$ | +| `pi_4` | $\pi / 4$ | +| `sqrt2 | $\sqrt(2)$ | +| `sqrt1_2 ` | $\sqrt(0.5)$ | + +The way one of these constants can be used in an expression is illustrated in the following example: + +```plumed +d: DISTANCE ATOMS=1,2 +# This function is evaluating the area of the circle whose radius is +# given by the distance between atoms 1 and 2. +c: CUSTOM ARG=d FUNC=pi*x*x PERIODIC=NO +PRINT ARG=c FILE=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. + +```plumed d: DISTANCE ATOMS=10,15 m: CUSTOM ARG=d FUNC=0.5*step(0.5-x)+x*step(x-0.5) PERIODIC=NO # check the function you are applying: PRINT ARG=d,m FILE=checkme RESTRAINT ARG=d AT=0.5 KAPPA=10.0 -\endplumedfile -(see also \ref DISTANCE, \ref PRINT, and \ref RESTRAINT) +``` -The meaning of the function `0.5*step(0.5-x)+x*step(x-0.5)` is: +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 could have been obtained using an \ref UPPER_WALLS -However, with CUSTOM you can create way more complex definitions. +Notice that the same result can be achieved by using [UPPER_WALLS](UPPER_WALLS.md) +However, with CUSTOM you can create much 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. +Notice that we can apply a force on the value `m` by using the [RESTRAINT](RESTRAINT.md) 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 -A possible continuity check with gnuplot is -\verbatim +```` # 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) -\endverbatim +```` -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. +## Using TIME as a variable -CUSTOM can be used in combination with \ref 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. -\plumedfile +Notice that you can use CUSTOM to implement a [MOVINGRESTRAINT](MOVINGRESTRAINT.md) as shown below. + +```plumed +t: TIME +d: DISTANCE ATOMS=1,2 +f: CUSTOM ARG=d,t FUNC=100*(d-((0.2-0.1)*t/100))^2 PERIODIC=NO +BIASVALUE ARG=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](shortcuts.md) 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: + +```plumed # take center of atoms 1 to 10 as reference point 1 p1: CENTER ATOMS=1-10 # take center of atoms 11 to 20 as reference point 2 @@ -152,13 +246,142 @@ onaxis: CUSTOM ARG=d13,d23,d12 FUNC=(0.5*(y^2-x^2)/z) PERIODIC=NO fromaxis: CUSTOM ARG=d13,d23,d12,onaxis VAR=x,y,z,o FUNC=(0.5*(y^2+x^2)-o^2-0.25*z^2) PERIODIC=NO PRINT ARG=onaxis,fromaxis - -\endplumedfile - -Notice that these equations have been used to combine \ref RMSD -from different snapshots of a protein so as to define -progression (S) and distance (Z) variables \cite perez2015atp. - +``` + +The equations in this input were also used to combine [RMSD](RMSD.md) 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. + +## 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. + +```plumed +a: ANGLE ATOMS1=1,2,3 ATOMS2=4,5,6 ATOMS3=7,8,9 +c: CUSTOM ARG=a FUNC=cos(x) PERIODIC=NO +PRINT ARG=c FILE=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. + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=4,5 ATOMS3=7,8 +a: ANGLE ATOMS1=1,2,3 ATOMS2=4,5,6 ATOMS3=7,8,9 +c: CUSTOM ARG=d,a FUNC=x*cos(y) PERIODIC=NO +PRINT ARG=c FILE=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. + +```plumed +d: DISTANCE ATOMS=1,2 +a: ANGLE ATOMS1=1,2,3 ATOMS2=1,2,4 ATOMS3=1,2,5 ATOMS4=1,2,6 +c: CUSTOM ARG=d,a FUNC=x*cos(y) PERIODIC=NO +PRINT ARG=c FILE=colvar +``` + +The multiplication of a scalar by a vector in the above input is done in [the usual way](https://en.wikipedia.org/wiki/Scalar_multiplication). +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. + +```plumed +c: CONSTANT VALUE=23 +d: DISTANCE ATOMS1=1,2 ATOMS2=4,5 ATOMS3=7,8 +f: CUSTOM ARG=d,c FUNC=x+y PERIODIC=NO +PRINT ARG=f FILE=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 \times $M$ the output matrix is also $N \times M$. The following example illustrates how you +can use this functionality to calculate all the angles between a set of bond vectors. + +```plumed +# Calculate the vectors connecting four atoms +d: DISTANCE COMPONENTS ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +# Calculate the norm of these four vectors +norm: CUSTOM ARG=d.x,d.y,d.z FUNC=sqrt(x*x+y*y+z*z) PERIODIC=NO +# Now calculate the directors of the vectors +norm_x: CUSTOM ARG=d.x,norm FUNC=x/y PEROIDIC=NO +norm_y: CUSTOM ARG=d.y,norm FUNC=x/y PEROIDIC=NO +norm_z: CUSTOM ARG=d.z,norm FUNC=x/y PEROIDIC=NO +# And combine all these directors in a matrix +stack: VSTACK ARG=norm_x,norm_y,norm_z +# Now calculate the matrix of dot products between directors (these are the cosines of the angles) +stackT: TRANSPOSE ARG=stack +cosa: MATRIX_PRODUCT ARG=stack,stackT +# And finally get the 4x4 matrix of angles and print it to a file +angles: CUSTOM ARG=cosa FUNC=acos(x) PERIODIC=NO +PRINT ARG=angles FILE=colvar +``` + +Notice that you can pass multiple $N\times M$ matrices in the input to a CUSTOM action as illustrated in the example below: + +```plumed +c1: CUSTOM VALUES=2,3,4,5 NROWS=2 NCOLS=2 +c2: CUSTOM VALUES=1,0,0,1 NROWS=2 NCOLS=2 +f: CUSTOM ARG=c1,c2 FUNC=x*y PEIRODIC=NO +PRINT ARG=f FILE=colvar +``` + +The four by four matrix that is calculated by the custom action in this input is given by: + +$$ +f = \left( +\begin{matrix} +2 & 0 \\ +0 & 5 +\end{matrix} +\right) +$$ + +which is the element-wise [Hadamard product](https://en.wikipedia.org/wiki/Hadamard_product_(matrices)) 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](https://en.wikipedia.org/wiki/Matrix_multiplication) you should use the [MATRIX_PRODUCT](MATRIX_PRODUCT.md) comamnd. +Similarly, if you want to calculate the product of a matrix and a vector you should use the [MATRIX_VECTOR_PRODUCT](MATRIX_VECTOR_PRODUCT.md) +command. + +Lastly, note that you can pass a mixture of scalars and $N\times 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\times 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) = -k_BT\log[H(s)]$ as illustrated in the input below: + +```plumed +x: DISTANCE ATOMS=1,2 +hA: HISTOGRAM ARG=x GRID_MIN=0.0 GRID_MAX=3.0 GRID_BIN=100 BANDWIDTH=0.1 +fE: CUSTOM ARG=hA FUNC=-2.5*log(x) PERIODIC=NO +DUMPGRID ARG=fE FILE=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. + +```plumed +# Evaluate the FCC order parameter for all of the atoms +fcc: FCCUBIC SPECIES=1-5184 SWITCH={CUBIC D_0=1.2 D_MAX=1.5} ALPHA=27 +# Calculate the distance between each atom and the origin on atom 1 +dens_dist: DISTANCES ORIGIN=1 ATOMS=fcc COMPONENTS +# 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: KDE HEIGHTS=fcc_n ARG=dens_dist.x,dens_dist.y,dens_dist.z GRID_BIN=14,14,28 BANDWIDTH=1.0,1.0,1.0 +# Estimate the density of atoms at each point in the box +ones: ONES SIZE=5184 +dens_denom: KDE ARG=dens_dist.x,dens_dist.y,dens_dist.z GRID_BIN=14,14,28 HEIGHTS=ones BANDWIDTH=1.0,1.0,1.0 +# Now calculate the average value of the order parameter at each point in the box +dens: CUSTOM ARG=dens_numer,dens_denom FUNC=x/y PERIODIC=NO +DUMPCUBE ARG=dens FILE=dens.cube FMT=%8.4f +``` */ //+ENDPLUMEDOC @@ -242,11 +465,20 @@ PLUMED_REGISTER_ACTION(MatrixCustom,"MATHEVAL_MATRIX") /* An alias to the CUSTOM function that can also be used to calaculate combinations of variables using a custom expression. -Documentation for this action is identical to that for \ref CUSTOM +The documentation for this action is identical to that for [CUSTOM](CUSTOM.md). You can thus use it to evaluate a evaluate an arbitrary function as in the following example input: + +```plumed +dAB: DISTANCE ATOMS=10,12 +dAC: DISTANCE ATOMS=10,15 +diff: MATHEVAL ARG=dAB,dAC FUNC=y-x PERIODIC=NO +# notice: the previous line could be replaced with the following +# diff: COMBINE ARG=dAB,dAC COEFFICIENTS=-1,1 +METAD ARG=diff SIGMA=0.1 HEIGHT=0.5 BIASFACTOR=10 PACE=100 +``` This alias is kept in order to maintain compatibility with previous PLUMED versions. However, notice that as of PLUMED 2.5 the libmatheval library is not linked anymore, -and the \ref MATHEVAL function is implemented using the Lepton library. +and that the MATHEVAL action evaluates functions [the Lepton library](https://simtk.org/projects/lepton). \par Examples @@ -269,6 +501,7 @@ void Custom::registerKeywords(Keywords& keys) { keys.add("compulsory","FUNC","the function you wish to evaluate"); keys.add("optional","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."); keys.setValueDescription("scalar/vector/matrix/grid","an arbitrary function"); + keys.addDOI("10.1093/nar/gkv872"); } void Custom::read( ActionWithArguments* action ) { diff --git a/src/function/Ensemble.cpp b/src/function/Ensemble.cpp index 1121f9d976..6ff84e1e60 100644 --- a/src/function/Ensemble.cpp +++ b/src/function/Ensemble.cpp @@ -31,17 +31,18 @@ namespace function { /* Calculates the replica averaging of a collective variable over multiple replicas. -Each collective variable is averaged separately and stored in a component labelled label.cvlabel. +Each collective variable is averaged separately and stored in a component labelled _label_.cvlabel. -\par Examples +## Examples The following input tells plumed to calculate the distance between atoms 3 and 5 and the average it over the available replicas. -\plumedfile + +```plumed dist: DISTANCE ATOMS=3,5 ens: ENSEMBLE ARG=dist PRINT ARG=dist,ens.dist -\endplumedfile +``` */ //+ENDPLUMEDOC diff --git a/src/function/FuncPathGeneral.cpp b/src/function/FuncPathGeneral.cpp index 4dd0ada991..838a8d9336 100644 --- a/src/function/FuncPathGeneral.cpp +++ b/src/function/FuncPathGeneral.cpp @@ -32,26 +32,26 @@ namespace function { /* This function calculates path collective variables (PCVs) using an arbitrary combination of collective variables. -The method used to calculate the PCVs that is used in this method is described in \cite Hovan2019. +The method used to calculate the PCVs that is used in this method is described in the paper from the bibliography below. This variable computes the progress along a given set of frames that is provided in an input file ("s" component) and the distance from them ("z" component). The input file could be a colvar file generated with plumed driver on a trajectory containing the frames. The metric for the path collective variables takes the following form: -\f[ +$$ R[X - X_i] = \sum_{j=1}^M c_j^2 (x_j - x_{i,j})^2\,. -\f] +$$ -Here, the coefficients \f$c_j\f$ determine the relative weights of the collective variables \f$c_j\f$ in the metric. +Here, the coefficients $c_j$ determine the relative weights of the collective variables $c_j$ in the metric. A value for the lambda coefficient also needs to be provided, typically chosen in such a way that it ensures a smooth variation of the "s" component. -\par Examples +## Examples This command calculates the PCVs using the values from the file COLVAR_TRAJ and the provided values for the lambda and the coefficients. Since the columns in the file were not specified, the first one will be ignored (assumed to correspond to the time) and the rest used. -\plumedfile +```plumed FUNCPATHGENERAL ... LABEL=path LAMBDA=12.2 @@ -59,13 +59,13 @@ REFERENCE=COLVAR_TRAJ COEFFICIENTS=0.3536,0.3536,0.3536,0.3536,0.7071 ARG=d1,d2,d,t,drmsd ... FUNCPATHGENERAL -\endplumedfile +``` The command below is a variation of the previous one, specifying a subset of the collective variables and using a neighbor list. The columns are zero-indexed. The neighbor list will include the 10 closest frames and will be recalculated every 20 steps. -\plumedfile +```plumed FUNCPATHGENERAL ... LABEL=path LAMBDA=5.0 @@ -76,7 +76,7 @@ ARG=d2,d,t NEIGH_SIZE=10 NEIGH_STRIDE=20 ... FUNCPATHGENERAL -\endplumedfile +``` */ //+ENDPLUMEDOC @@ -163,6 +163,7 @@ void FuncPathGeneral::registerKeywords(Keywords& keys) { keys.add("optional", "NEIGH_STRIDE", "How often the neighbor list needs to be calculated in time units"); keys.addOutputComponent("s", "default", "scalar","Position on the path"); keys.addOutputComponent("z", "default", "scalar","Distance from the path"); + keys.addDOI("10.1021/acs.jctc.8b00563"); } FuncPathGeneral::FuncPathGeneral(const ActionOptions&ao): diff --git a/src/function/FuncPathMSD.cpp b/src/function/FuncPathMSD.cpp index 5070c284f9..acce1172ed 100644 --- a/src/function/FuncPathMSD.cpp +++ b/src/function/FuncPathMSD.cpp @@ -30,63 +30,31 @@ namespace function { /* This function calculates path collective variables. -This is the Path Collective Variables implementation -( see \cite brand07 ). +This is the Path Collective Variables implementation described in the paper from the bibliography. This variable computes the progress along a given set of frames that is provided in input ("s" component) and the distance from them ("z" component). It is a function of mean squared displacement that are obtained by the joint use of mean squared displacement variables with the SQUARED flag (see below). -\par Examples +## Examples Here below is a case where you have defined three frames and you want to calculate the progress along the path and the distance from it in p1 -\plumedfile -t1: RMSD REFERENCE=frame_1.pdb TYPE=OPTIMAL SQUARED -t2: RMSD REFERENCE=frame_21.pdb TYPE=OPTIMAL SQUARED -t3: RMSD REFERENCE=frame_42.pdb TYPE=OPTIMAL SQUARED +```plumed +#SETTINGS INPUTFILES=regtest/trajectories/path_msd/frame_1.dat,regtest/trajectories/path_msd/frame_21.dat,regtest/trajectories/path_msd/frame_42.dat +t1: RMSD REFERENCE=regtest/trajectories/path_msd/frame_1.pdb TYPE=OPTIMAL SQUARED +t2: RMSD REFERENCE=regtest/trajectories/path_msd/frame_21.pdb TYPE=OPTIMAL SQUARED +t3: RMSD REFERENCE=regtest/trajectories/path_msd/frame_42.pdb TYPE=OPTIMAL SQUARED p1: FUNCPATHMSD ARG=t1,t2,t3 LAMBDA=500.0 PRINT ARG=t1,t2,t3,p1.s,p1.z STRIDE=1 FILE=colvar FMT=%8.4f -\endplumedfile - -For this input you would then define the position of the reference coordinates in three separate pdb files. The contents of the -file frame_1.pdb are shown below: - -\auxfile{frame_1.pdb} -ATOM 1 CL ALA 1 -3.171 0.295 2.045 1.00 1.00 -ATOM 5 CLP ALA 1 -1.819 -0.143 1.679 1.00 1.00 -ATOM 6 OL ALA 1 -1.177 -0.889 2.401 1.00 1.00 -ATOM 7 NL ALA 1 -1.313 0.341 0.529 1.00 1.00 -ATOM 8 HL ALA 1 -1.845 0.961 -0.011 1.00 1.00 -END -\endauxfile - -This is then frame.21.pdb: - -\auxfile{frame_21.pdb} -ATOM 1 CL ALA 1 -3.089 1.850 1.546 1.00 1.00 -ATOM 5 CLP ALA 1 -1.667 1.457 1.629 1.00 1.00 -ATOM 6 OL ALA 1 -0.974 1.868 2.533 1.00 1.00 -ATOM 7 NL ALA 1 -1.204 0.683 0.642 1.00 1.00 -ATOM 8 HL ALA 1 -1.844 0.360 -0.021 1.00 1.00 -END -\endauxfile - -and finally this is frame_42.pdb: - -\auxfile{frame_42.pdb} -ATOM 1 CL ALA 1 -3.257 1.605 1.105 1.00 1.00 -ATOM 5 CLP ALA 1 -1.941 1.459 0.447 1.00 1.00 -ATOM 6 OL ALA 1 -1.481 2.369 -0.223 1.00 1.00 -ATOM 7 NL ALA 1 -1.303 0.291 0.647 1.00 1.00 -ATOM 8 HL ALA 1 -1.743 -0.379 1.229 1.00 1.00 -END -\endauxfile - -This second example shows how to define a PATH in \ref CONTACTMAP space: - -\plumedfile +``` + +You can see that the reference coordinates here are described in three separate pdb files that you view above. + +This second example shows how to define a PATH in [CONTACTMAP](CONTACTMAP.md) space: + +```plumed CONTACTMAP ... ATOMS1=1,2 REFERENCE1=0.1 ATOMS2=3,4 REFERENCE2=0.5 @@ -119,16 +87,17 @@ CMDIST p1: FUNCPATHMSD ARG=c1,c2,c3 LAMBDA=500.0 PRINT ARG=c1,c2,c3,p1.s,p1.z STRIDE=1 FILE=colvar FMT=%8.4f -\endplumedfile +``` -This third example shows how to define a PATH in \ref PIV space: +This third example shows how to define a PATH in [PIV](PIV.md) space: -\plumedfile +```plumed +#SETTINGS INPUTFILES=regtest/piv/rt-piv-distance/Liq.pdb,regtest/piv/rt-piv-distance/Ice.pdb PIV ... LABEL=c1 PRECISION=1000 NLIST -REF_FILE=Ref1.pdb +REF_FILE=regtest/piv/rt-piv-distance/Liq.pdb PIVATOMS=2 ATOMTYPES=A,B ONLYDIRECT @@ -144,7 +113,7 @@ PIV ... LABEL=c2 PRECISION=1000 NLIST -REF_FILE=Ref2.pdb +REF_FILE=regtest/piv/rt-piv-distance/Ice.pdb PIVATOMS=2 ATOMTYPES=A,B ONLYDIRECT @@ -160,7 +129,7 @@ NL_SKIN=0.1,0.1 p1: FUNCPATHMSD ARG=c1,c2 LAMBDA=0.180338 METAD ARG=p1.s,p1.z SIGMA=0.01,0.2 HEIGHT=0.8 PACE=500 LABEL=res PRINT ARG=c1,c2,p1.s,p1.z,res.bias STRIDE=500 FILE=colvar FMT=%15.6f -\endplumedfile +``` */ //+ENDPLUMEDOC @@ -224,6 +193,7 @@ void FuncPathMSD::registerKeywords(Keywords& keys) { keys.add("optional","NEIGH_STRIDE","how often the neighbor list needs to be calculated in time units"); keys.addOutputComponent("s","default","scalar","the position on the path"); keys.addOutputComponent("z","default","scalar","the distance from the path"); + keys.addDOI("10.1063/1.2432340"); } FuncPathMSD::FuncPathMSD(const ActionOptions&ao): Action(ao), diff --git a/src/function/FuncSumHills.cpp b/src/function/FuncSumHills.cpp index 627063b717..580271b298 100644 --- a/src/function/FuncSumHills.cpp +++ b/src/function/FuncSumHills.cpp @@ -41,7 +41,7 @@ This function is intended to be called by the command line tool sum_hills. It i In the future one could implement periodic integration during the metadynamics or straightforward MD as a tool to check convergence -\par Examples +## Examples There are currently no examples for this keyword. diff --git a/src/function/Highest.cpp b/src/function/Highest.cpp index 00ce59ceff..94653f74a5 100644 --- a/src/function/Highest.cpp +++ b/src/function/Highest.cpp @@ -32,7 +32,74 @@ namespace function { /* This function can be used to find the highest colvar by magnitude in a set. -\par Examples +This action allows you to find the highest of the input arguments. As a first example of how it might be used consider the following input: + +```plumed +d1: DISTANCE ATOMS=1,2 +d2: DISTANCE ATOMS=3,4 +h1: HIGHEST ARG=d1,d2 +PRINT ARG=h1 FILE=colvar +``` + +The value, `h1`, that is output to the file `colvar` here will be equal to `d1` if `d1>d2` and will be equal to `d2` if `d2>d1`. In other words, if +all the arguments input to a HIGHEST action are scalars then the output value will be a scalar that is equal to the largest of the input arguments. +Notice that you can also use this command with more than two arguments as illustrated below: + +```plumed +d1: DISTANCE ATOMS=1,2 +d2: DISTANCE ATOMS=3,4 +d3: DISTANCE ATOMS=5,6 +d4: DISTANCE ATOMS=7,8 +h1: HIGHEST ARG=d1,d2,d3,d4 +PRINT ARG=h1 FILE=colvar +``` + +## Using a single vector as input + +Instead of inputting multiple scalars you can input a single vector to this action instead as is illustrated below: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 +h1: HIGHEST ARG=d +PRINT ARG=h1 FILE=colvar +``` + +The output from this action is a single scalar once again. This single scalar is equal to the largest element of the input vector. + +## Using multiple vectors in input + +If you input multiple vectors with the same numbers of elements to this action, as shown below, the output will be a vector. + + +```plumed +d1: DISTANCE ATOMS1=1,2 ATOMS2=3,4 +d2: DISTANCE ATOMS1=5,6 ATOMS2=7,8 +d3: DISTANCE ATOMS1=9,10 ATOMS2=11,12 +h2: HIGHEST ARG=d1,d2,d3 +PRINT ARG=h2 FILE=colvar +``` + +The elements of the output vector here are determined by doing an elementwise comparison of the elements in the input vectors. In the above +input the first element of `h2` is equal to the distance between atoms 1 and 2 if this distance is larger than the distances between atoms 5 and 6 and the distance between atoms 9 and 10. +By the same token the second element of `h2` is equal to the distance between atoms 3 and 4 if this is larger than the distance between atoms 7 and 8 and the distance between atoms 11 and 12. +In other words, if the elements of the $j$th input vector are given by $v_i^{(j)}$ then the elements of the output vector, $h_i$ are given by: + +$$ +h_i = \max_j v_i^{(j)} +$$ + +Notice that you can also use a combination of scalars and vectors in the input to this action as shown below: + +```plumed +c: CONSTANT VALUE=0.05 +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 +h: HIGHEST ARG=c,d +PRINT ARG=h FILE=colvar +``` + +For the input above the HIGHEST action outputs a vector with two elements. The elements of this vector are equal to the distances between the pairs +of atoms that are specified in the DISTANCE command as long as those distances are greater than 0.05 nm. If either of the two input distances is less +than 0.05 nm then the corresponding value in the vector `h` is set equal to 0.05 nm. */ //+ENDPLUMEDOC @@ -59,7 +126,74 @@ Calculate the largest element in a vector of inputs /* This function can be used to find the lowest colvar by magnitude in a set. -\par Examples +This action allows you to find the lowest of the input arguments. As a first example of how it might be used consider the following input: + +```plumed +d1: DISTANCE ATOMS=1,2 +d2: DISTANCE ATOMS=3,4 +l1: LOWEST ARG=d1,d2 +PRINT ARG=l1 FILE=colvar +``` + +The value, `l1`, that is output to the file `colvar` here will be equal to `d1` if `d1 d_0\f$ the function decays smoothly to 0. -The various switching functions available in PLUMED differ in terms of how this decay is performed. - -Where there is an accepted convention in the literature (e.g. \ref COORDINATION) on the form of the -switching function we use the convention as the default. However, the flexibility to use different -switching functions is always present generally through a single keyword. This keyword generally -takes an input with the following form: - -\verbatim -KEYWORD={TYPE } -\endverbatim - -The following table contains a list of the various switching functions that are available in PLUMED 2 -together with an example input. - - - - - - - - - - - - - - - - - - - - - - -
TYPE FUNCTION EXAMPLE INPUT DEFAULT PARAMETERS
RATIONAL -\f$ -s(r)=\frac{ 1 - \left(\frac{ r - d_0 }{ r_0 }\right)^{n} }{ 1 - \left(\frac{ r - d_0 }{ r_0 }\right)^{m} } -\f$ - -{RATIONAL R_0=\f$r_0\f$ D_0=\f$d_0\f$ NN=\f$n\f$ MM=\f$m\f$} - \f$d_0=0.0\f$, \f$n=6\f$, \f$m=2n\f$
EXP -\f$ -s(r)=\exp\left(-\frac{ r - d_0 }{ r_0 }\right) -\f$ - -{EXP R_0=\f$r_0\f$ D_0=\f$d_0\f$} - \f$d_0=0.0\f$
GAUSSIAN -\f$ -s(r)=\exp\left(-\frac{ (r - d_0)^2 }{ 2r_0^2 }\right) -\f$ - -{GAUSSIAN R_0=\f$r_0\f$ D_0=\f$d_0\f$} - \f$d_0=0.0\f$
SMAP -\f$ -s(r) = \left[ 1 + ( 2^{a/b} -1 )\left( \frac{r-d_0}{r_0} \right)^a \right]^{-b/a} -\f$ - -{SMAP R_0=\f$r_0\f$ D_0=\f$d_0\f$ A=\f$a\f$ B=\f$b\f$} - \f$d_0=0.0\f$
Q -\f$ -s(r) = \frac{1}{1 + \exp(\beta(r_{ij} - \lambda r_{ij}^0))} -\f$ - -{Q REF=\f$r_{ij}^0\f$ BETA=\f$\beta\f$ LAMBDA=\f$\lambda\f$ } - \f$\lambda=1.8\f$, \f$\beta=50 nm^-1\f$ (all-atom)
\f$\lambda=1.5\f$, \f$\beta=50 nm^-1\f$ (coarse-grained)
CUBIC -\f$ -s(r) = (y-1)^2(1+2y) \qquad \textrm{where} \quad y = \frac{r - r_1}{r_0-r_1} -\f$ - -{CUBIC D_0=\f$r_1\f$ D_MAX=\f$r_0\f$} -
TANH -\f$ -s(r) = 1 - \tanh\left( \frac{ r - d_0 }{ r_0 } \right) -\f$ - -{TANH R_0=\f$r_0\f$ D_0=\f$d_0\f$} -
COSINUS -\f$s(r) =\left\{\begin{array}{ll} +This action takes one argument, $r$ and evaluates the following function: + +$$ +w(r) = s(r) +$$ + +The function $s(r)$ here is a switching function so the output value $w$ is a number between 0 and 1. +Switching functions are typically used to determine if an input value is less than some cutoff. The value +of $w$ the switches smoothly from one to zero as the input value $r$ crosses the threshold of interest. + +The following example, shows how we can apply a switching function on the instantaneous value of the +distance between atom 1 and atom 2. + +```plumed +d: DISTANCE ATOMS=1,2 +s: LESS_THAN ARG=d SWITCH={RATIONAL R_0=0.2} +``` + +The output here is close to one when the distance between atoms 1 and 2 is less than 0.2 nm close to zero +for values that are greater than 0.2. + +## Non rank zero arguments + +Instead of passing a single scalar in the input to the `LESS_THAN` action you can pass a single vector as shown here: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +b: LESS_THAN ARG=d SWITCH={RATIONAL R_0=0.2} +``` + +The input to the `LESS_THAN` action here is a vector with four elements. The output from the action `b` is similarly +a vector with four elements. In calculating the elements of this vector PLUMED applies the function described in the previous +section on each of the distances in turn. The first element of `b` thus tells you if the distance between atoms 1 and 2 is less than +0.2 nm, the second element tells you if the distance between atoms 3 and 4 is less than 0.2 nm and so on. + +You can use the commands in the above example input to evaluate the number of distances that are less than a cutoff as follows: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +b: LESS_THAN ARG=d SWITCH={RATIONAL R_0=0.2} +s: SUM ARG=b PERIODIC=NO +PRINT ARG=s FILE=colvar +``` + +The final scalar that is output here is evaluated using the following summation: + +$$ +s = \sum_i s(d_i) +$$ + +where the sum over $i$ here runs over the four distances in the above expression. This scalar tells you the number of distances that are +less than 0.2 nm. + +Notice that you can do something similar with a matrix as input as shown below: + +```plumed +d: DISTANCE_MATRIX GROUPA=1-10 GROUPB=11-20 +b: LESS_THAN ARG=d SWITCH={RATIONAL R_0=0.2} +s: SUM ARG=b PERIODIC=NO +PRINT ARG=s FILE=colvar +``` + +This input tells PLUMED to calculate the 100 distances between the atoms in the two input groups. The final value that is printed to the colvar file then +tells you how many of these distances are less than 0.2 nm. + +## Switching functions types + +PLUMED allows you to use a range of different switching function types. Most of these +require you to provide at least one input parameter $r_0$. The switching function is then defined so that for +$r \le d_0 \quad s(r)=1.0$ while for $r > d_0$ the function decays smoothly to 0. By changing the switching +function you are using you change the decay that occurs in the switching function for $r$ values that are greater +that $d_0$. + +You can specify the value at which the the switching function goes to zero by using the D_MAX keyword. +PLUMED will ensure that the swtiching function is definitely zero for for input values that are greater than +or equal to D_MAX by by stretching and shifting the function using the following transformations. + +$ +s(r) = \frac{s'(r)-s'(d_{max})}{s'(0)-s'(d_{max})} +$ + +The various expressions that are used for $s'(r)$ in the above expression are described in the following sections. +Scaling the switching function so that it is exactly zero at $d_{max}$ using the transformation described above +has been the default behaviour within PLUMED since version 2.2. +If you wish to use a D_MAX parameter and the $s'(r)$ functions described in the following sections directly you can use the +keyword `NOSTRETCH`. However, the advangage of performing the stretching and scaling in this way is that the function has +no discontinuities. If you use the `NOSTRETCH` option the switching function may have a discontinuity at $d_{max}$. + +### Rational switching function + +The rational switching function is the most commonly used of the switching functions. The implementation of this function within PLUMED has been carefully +optimised so calculations using this switching function should be fast. + +For this function $s'(r)$ has the following functional form: + +$$ +s'(r) = \begin{cases} +1 & \textrm{if} \quad r d_0 + r_0 - \end{array}\right. -\f$ - -{COSINUS R_0=\f$r_0\f$ D_0=\f$d_0\f$} -
CUSTOM -\f$ -s(r) = FUNC -\f$ - -{CUSTOM FUNC=1/(1+x^6) R_0=\f$r_0\f$ D_0=\f$d_0\f$} -
- -Notice that most commonly used rational functions are better optimized and might run faster. - -Notice that for backward compatibility we allow using `MATHEVAL` instead of `CUSTOM`. -Also notice that if the a `CUSTOM` switching function only depends on even powers of `x` it can be -made faster by using `x2` as a variable. For instance -\verbatim -{CUSTOM FUNC=1/(1+x2^3) R_0=0.3} -\endverbatim -is equivalent to -\verbatim -{CUSTOM FUNC=1/(1+x^6) R_0=0.3} -\endverbatim -but runs faster. The reason is that there is an expensive square root calculation that can be optimized out. - - -\attention -With the default implementation CUSTOM is slower than other functions -(e.g., it is slower than an equivalent RATIONAL function by approximately a factor 2). -Checkout page \ref Lepton to see how to improve its performance. - -For all the switching functions in the above table one can also specify a further (optional) parameter using the parameter -keyword D_MAX to assert that for \f$r>d_{\textrm{max}}\f$ the switching function can be assumed equal to zero. -In this case the function is brought smoothly to zero by stretching and shifting it. -\verbatim -KEYWORD={RATIONAL R_0=1 D_MAX=3} -\endverbatim -the resulting switching function will be -\f$ -s(r) = \frac{s'(r)-s'(d_{max})}{s'(0)-s'(d_{max})} -\f$ -where -\f$ -s'(r)=\frac{1-r^6}{1-r^{12}} -\f$ -Since PLUMED 2.2 this is the default. The old behavior (no stretching) can be obtained with the -NOSTRETCH flag. The NOSTRETCH keyword is only provided for backward compatibility and might be -removed in the future. Similarly, the STRETCH keyword is still allowed but has no effect. - -Notice that switching functions defined with the simplified syntax are never stretched -for backward compatibility. This might change in the future. + 0 +$$ -\par Examples +No stretching is required for this type of switching function as its functional form ensures that it is zero at $d_0+r_0$ + +### Custom switching function + +If you want to use a switching function that is different to all of the functions listed above you can use the cusom option that is illustrated below: + +```plumed +d: DISTANCE ATOMS=1,2 +s: LESS_THAN ARG=d SWITCH={CUSTOM FUNC=1/(1+x^6) D_0=0.1 R_0=0.1 D_MAX=10} +``` + +This option allows you to use the lepton library that is used to implement the [CUSTOM](CUSTOM.md) action to evaluate your switching function. With this +option you specify the functional form for $s'(r)$ by providing a function of `x` to the `FUNC` keyword. The `x` that enters the switching function +definition that you provide is given by: + +$$ +x = \frac{r - d_0}{r_0} +$$ + +Notice, that you can also express your switching function in terms of $x^2$ as illustrated in the input below: + +```plumed +d: DISTANCE ATOMS=1,2 +s: LESS_THAN ARG=d SWITCH={CUSTOM FUNC=1/(1+x2^3) D_0=0.1 R_0=0.1 D_MAX=10} +``` + +which is equivalent to the earlier input with the CUSTOM switching function. However, using `x2` in place of `x` is often more computationally efficient +as you can avoid an expensive square root operation. Notice, lastly, that just as there is a [MATHEVAL](MATHEVAL.md) action that is equivalent to [CUSTOM](CUSTOM.md), +there is also a matheval equivalent that you can use here: + +```plumed +d: DISTANCE ATOMS=1,2 +s: LESS_THAN ARG=d SWITCH={MATHEVAL FUNC=1/(1+x2^3) R_0=0.1} +``` + +For this input $d_0$ is set to its default value of 0. Furthermore, as D_MAX is unset the stretching and scaling that +was described in the previous section is not performed. + +> [!CAUTION] +> With the default implementation CUSTOM is slower than other functions +> (e.g., it is slower than an equivalent RATIONAL function by approximately a factor 2). +> You can find information on how to improve its performance in the documenation for [CUSTOM](CUSTOM.md) */ //+ENDPLUMEDOC diff --git a/src/function/LocalEnsemble.cpp b/src/function/LocalEnsemble.cpp index 61a80a9794..a19197c165 100644 --- a/src/function/LocalEnsemble.cpp +++ b/src/function/LocalEnsemble.cpp @@ -31,15 +31,16 @@ namespace function { Calculates the average over multiple arguments. If more than one collective variable is given for each argument then they -are averaged separately. The average is stored in a component labelled label.cvlabel. +are averaged separately. The average is stored in a component labelled _label_.cvlabel. -\par Examples +## Examples The following input tells plumed to calculate the chemical shifts for four different proteins in the same simulation box then average them, calculated the sum of the squared deviation with respect to the experimental values and applies a linear restraint. -\plumedfile + +```plumed MOLINFO STRUCTURE=data/template.pdb chaina: GROUP ATOMS=1-1640 @@ -67,7 +68,7 @@ sthn: STATS ARG=(enshn\.csa\.hn_.*) PARARG=(csa\.exphn_.*) SQDEVSUM stnh: STATS ARG=(ensnh\.csa\.nh_.*) PARARG=(csa\.expnh_.*) SQDEVSUM res: RESTRAINT ARG=stca.*,stcb.*,stco.*,sthn.*,stnh.* AT=0.,0.,0.,0.,0. KAPPA=0.,0.,0.,0.,0 SLOPE=16.,16.,12.,24.,0.5 -\endplumedfile +``` */ //+ENDPLUMEDOC diff --git a/src/function/Moments.cpp b/src/function/Moments.cpp index a7f5b7c787..e0755b2411 100644 --- a/src/function/Moments.cpp +++ b/src/function/Moments.cpp @@ -32,9 +32,39 @@ namespace function { //+PLUMEDOC FUNCTION MOMENTS /* -Calculate the moments of the distribution of input quantities +Calculate central moments from the distribution of input quantities -\par Examples +This action takes a set of $N$ input arguments, $s_i$, and evaluates the $k$th central moment of the distribution of input arguments using: + +$$ +\mu_k = \frac{1}{N} \sum_{i=1}^N ( s_i - \langle s \rangle )^k \qquad \textrm{where} \qquad \langle s \rangle = \frac{1}{N} \sum_{i=1}^N s_i +$$ + +A single moments action can evaluate more than one central moment at once so, for example, the input below can be used to calculate the second +and third central moment for the distribution of the four input distances. + +```plumed +d12: DISTANCE ATOMS=1,2 +d13: DISTANCE ATOMS=1,3 +d14: DISTANCE ATOMS=1,4 +d15: DISTANCE ATOMS=1,5 +mv: MOMENTS ARG=d12,d13,d14,d15 POWERS=2,3 +PRINT ARG=mv.moment-2,mv.moment-3 FILE=colvar +``` + +Notice that you can also achieve the same result using the following input: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=1,3 ATOMS3=1,4 ATOMS4=1,5 +sort: SORT ARG=d +PRINT ARG=mv.moment-2,mv.moment-3 FILE=colvar +``` + +In this second case the four distances are passed to the MOMENTS action as a vector. The MOMENTS action then outputs 2 components - the +two central moments that were requested. + +These examples are representative the only two ways you can use this action. In input it can accept either a list of scalars or a single vector. +It does not accept matrices or a list of vectors in input. */ //+ENDPLUMEDOC diff --git a/src/function/MoreThan.cpp b/src/function/MoreThan.cpp index a02b93fc21..447114b295 100644 --- a/src/function/MoreThan.cpp +++ b/src/function/MoreThan.cpp @@ -35,7 +35,70 @@ namespace function { /* Use a switching function to determine how many of the input variables are more than a certain cutoff. -\par Examples +This action takes one argument, $r$ and evaluates the following function: + +$$ +w(s) = 1 - s(r) +$$ + +In this equation $s(r)$ is one of the switching functions described in the documentation for the action [LESS_THAN](LESS_THAN.md). +The output value $w$ is thus a number between 0 and 1 that tells you if the input value is greater than some cutoff. Furthermore, +the value of $w$ smoothly from zero to one as the input value $r$ crosses the threshold of interest so any function of this value +is differentiable. + +The following example, shows how we can apply the function above on the instantaneous value of the distance between atom 1 and 2. +The MORE_THAN action here is used to determine whether the input distance is greater than 0.2 nm. + +```plumed +d: DISTANCE ATOMS=1,2 +b: MORE_THAN ARG=d SWITCH={RATIONAL R_0=0.2} +``` + +You can use all the switching function options described in the documentation for [LESS_THAN](LESS_THAN.md) here in place of RATIONAL. + +## Non rank zero arguments + +Instead of passing a single scalar in the input to the `MORE_THAN` action you can pass a single vector as shown here: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +b: MORE_THAN ARG=d SWITCH={RATIONAL R_0=0.2} +``` + +The input to the `MORE_THAN` action here is a vector with four elements. The output from the action `b` is similarly +a vector with four elements. In calculating the elements of this vector PLUMED applies the function described in the previous +section on each of the distances in turn. The first element of `b` thus tells you if the distance between atoms 1 and 2 is between +greater than 0.2 nm, the second element tells you if the distance between atoms 3 and 4 is greater than 0.2 nm and so on. + +You can use the commands in the above example input to evaluate the number of distances that greater than a threshold as follows: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +b: MORE_THAN ARG=d SWITCH={RATIONAL R_0=0.2} +s: SUM ARG=b PERIODIC=NO +PRINT ARG=s FILE=colvar +``` + +The final scalar that is output here is evaluated using the following summation: + +$$ +s = \sum_i 1 - s(d_i) +$$ + +where the sum over $i$ here runs over the four distances in the above expression. This scalar tells you the number of distances that are +more than 0.2 nm. + +Notice that you can do something similar with a matrix as input as shown below: + +```plumed +d: DISTANCE_MATRIX GROUPA=1-10 GROUPB=11-20 +b: MORE_THAN ARG=d SWITCH={RATIONAL R_0=0.2} +s: SUM ARG=b PERIODIC=NO +PRINT ARG=s FILE=colvar +``` + +This input tells PLUMED to calculate the 100 distances between the atoms in the two input groups. The final value that is printed to the colvar file then +tells you how many of these distances are greater than 0.2 nm. */ //+ENDPLUMEDOC diff --git a/src/function/Piecewise.cpp b/src/function/Piecewise.cpp index 4e833cd975..81fa8f7003 100644 --- a/src/function/Piecewise.cpp +++ b/src/function/Piecewise.cpp @@ -31,37 +31,60 @@ namespace function { /* Compute a piece wise straight line through its arguments that passes through a set of ordered control points. +This action can be used to calculate a piecewise linear function of an input argument such as the one given below: + +$$ +f(x) = \begin{cases} +10 & \textrm{if} \quad x<1 \\ +10 + \frac{\pi - 10}{2-1}(x-1) & \textrm{if} \quad 1 \le x < 2 \\ +\pi + \frac{10 - \pi}{3-2}(x-2) & \textrm{if} \quad 2 \le x \le 3 \\ +10 & \textrm{otherwise} +\end{cases} +$$ + +The example shown below illustrates how one can use PLUMED to evaluate the function described above for the distance +between atom 1 and atom 2. + +```plumed +dist1: DISTANCE ATOMS=1,10 +pw: PIECEWISE POINT0=1,10 POINT1=2,PI POINT2=3,10 ARG=dist1 +PRINT ARG=pw FILE=colvar +``` + +As you can see from the example above, the control points for the picewise function are passed using the `POINT0=...` `POINT1=...` syntax. +You can specify as many of these control points as you want. These control points then serce as the $x_i$ and $y_i$ values in the following expression. + For variables less than the first (greater than the last) point, the value of the first (last) point is used. -\f[ +$$ \frac{y_{i+1}-y_i}{x_{i+1}-x_i}(s-x_i)+y_i ; if x_ix_{N-1} -\f] -\f[ -y_1 ; if xlabel.1, the second lowest will be labelled label.2 and so on. - -\par Examples - -The following input tells plumed to print the distance of the closest and of -the farthest atoms to atom 1, chosen among atoms from 2 to 5 -\plumedfile +```plumed d12: DISTANCE ATOMS=1,2 d13: DISTANCE ATOMS=1,3 d14: DISTANCE ATOMS=1,4 d15: DISTANCE ATOMS=1,5 sort: SORT ARG=d12,d13,d14,d15 PRINT ARG=sort.1,sort.4 -\endplumedfile +``` + +Notice that you can also achieve the same result using the following input: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=1,3 ATOMS3=1,4 ATOMS4=1,5 +sort: SORT ARG=d +PRINT ARG=sort.1,sort.4 +``` + +In this second case the four distances are passed to the SORT action as a vector. The SORT action then outputs 4 components - the same number of components as there +are elements in the input vector - that contain the elements of the input vector in order of increasing magnitude. + +These examples are representative the only two ways you can use this action. In input it can accept either a list of scalars or a single vector. +It does not accept matrices or a list of vectors in input. */ //+ENDPLUMEDOC diff --git a/src/function/Stats.cpp b/src/function/Stats.cpp index f3876c6aac..cc94650598 100644 --- a/src/function/Stats.cpp +++ b/src/function/Stats.cpp @@ -34,20 +34,20 @@ slope and the intercept of a linear fit. The reference values can be either provided as values using PARAMETERS or using value without derivatives from other actions using PARARG (for example using experimental values from collective variables such as -\ref CS2BACKBONE, \ref RDC, \ref NOE, \ref PRE). +[CS2BACKBONE](CS2BACKBONE.md), [RDC](RDC.md), [NOE](NOE.md), [PRE](PRE.md)). \par Examples The following input tells plumed to print the distance between three couple of atoms and compare them with three reference distances. -\plumedfile +```plumed d1: DISTANCE ATOMS=10,50 d2: DISTANCE ATOMS=1,100 d3: DISTANCE ATOMS=45,75 st: STATS ARG=d1,d2,d3 PARAMETERS=1.5,4.0,2.0 PRINT ARG=d1,d2,d3,st.* -\endplumedfile +``` */ //+ENDPLUMEDOC diff --git a/src/function/Sum.cpp b/src/function/Sum.cpp index 3db505117b..7601e17afa 100644 --- a/src/function/Sum.cpp +++ b/src/function/Sum.cpp @@ -30,7 +30,26 @@ /* Calculate the sum of the arguments -\par Examples +This action takes a single vector or a single matrix in input. The output is a scalar +that contains the sum of all the elements in the input vector/matrix. This action is +very useful if you want to do calculations like the one illustrated in this example: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +b: LESS_THAN ARG=d SWITCH={RATIONAL R_0=0.1} +s: SUM ARG=b PERIODIC=NO +PRINT ARG=s FILE=colvar +``` + +This example calculates and outputs the number of distances that are less than 0.1 nm. + +You can do something similar by summing the elements of a matrix as shown below: + +```plumed +c: CONTACT_MAP SPECIES=1-100 SWITCH={RATIONAL R_0=0.1} +s: SUM ARG=c PERIODIC=NO +PRINT ARG=s FILE=colvar +``` */ //+ENDPLUMEDOC @@ -57,7 +76,25 @@ Calculate the SUM of the set of input scalars /* Calculate the arithmetic mean of the elements in a vector -\par Examples +This action takes a single vector or a single matrix in input. The output is a scalar +that contains the mean of all the elements in the input vector/matrix. This action is +useful if you want do to calculations like the one illustrated in this example: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +m: MEAN ARG=d PERIODIC=NO +PRINT ARG=m FILE=colvar +``` + +The output from the MEAN action here is the average over the four distances that are evaluated by the +DISTANCE action. Notice that you can also do the calculation above using: + +```plumed +d: DISTANCE ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6 ATOMS4=7,8 +s: SUM ARG=d PERIODIC=NO +m: CUSTOM ARG=s FUNC=x/4 PERIODIC=NO +PRINT ARG=m FILE=colvar +``` */ //+ENDPLUMEDOC diff --git a/src/generic/Constant.cpp b/src/generic/Constant.cpp index d594345fef..479976aafc 100644 --- a/src/generic/Constant.cpp +++ b/src/generic/Constant.cpp @@ -108,6 +108,17 @@ sss: SORT ARG=cn,dis PRINT ARG=sss.1 ``` +Lastly, note that if you have an action that only takes constant values in input its output values will be treated as constants. For example, +in the following input the values `d` and `f` are evaluated on every step. `c`, however, is only evaluated once during start up. + +```plumed +p: CONSTANT VALUE=1.0 +c: CUSTOM ARG=p FUNC=2*x+1 PERIODIC=NO +d: DISTANCE ATOMS=1,2 +f: CUSTOM ARG=p,d FUNX=x*y PERIODIC=NO +PRINT ARG=f FILE=colvar STRIDE=1 +``` + */ //+ENDPLUMEDOC