Added new method for links to switching function documentation

This commit addresses something that has bothered me for a while; namely, how we should
provide the links to the parts of the manual on swiching function when you encounter a keyword
like switch.  I would ideally like to provide the link to this page both in the tooltip that is
generated for the annotated inputs and in the tables that contain the syntax.

This commit addresses this problem.  You can now use the command keys.linkActionInDocs when you
register the keyword in registerKeywords.  Links to the manual pages for relevant actions will then
be included in the manual and in tooltips.

As part of this I have also moved the documentation for switching function to the action LESS_THAN
and the documentation for HistogramBead to BETWEEN as this is where these classes are used in their
most basic form.

src/adjmat/BridgeMatrix.cpp

@@ -75,10 +75,13 @@ void BridgeMatrix::registerKeywords( Keywords& keys ) {
   keys.add("atoms","BRIDGING_ATOMS","The list of atoms that can form the bridge between the two interesting parts "
            "of the structure.");
   keys.add("optional","SWITCH","The parameters of the two switchingfunction in the above formula");
+  keys.linkActionInDocs("SWITCH","LESS_THAN");
   keys.add("optional","SWITCHA","The switchingfunction on the distance between bridging atoms and the atoms in "
            "group A");
+  keys.linkActionInDocs("SWITCHA","LESS_THAN");
   keys.add("optional","SWITCHB","The switchingfunction on the distance between the bridging atoms and the atoms in "
            "group B");
+  keys.linkActionInDocs("SWITCHB","LESS_THAN");
 }
 
 BridgeMatrix::BridgeMatrix(const ActionOptions&ao):

src/adjmat/ContactMatrix.cpp

@@ -86,6 +86,7 @@ void ContactMatrix::registerKeywords( Keywords& keys ) {
   keys.add("optional","SWITCH","This keyword is used if you want to employ an alternative to the continuous swiching function defined above. "
            "The following provides information on the \\ref switchingfunction that are available. "
            "When this keyword is present you no longer need the NN, MM, D_0 and R_0 keywords.");
+  keys.linkActionInDocs("SWITCH","LESS_THAN");
 }
 
 ContactMatrix::ContactMatrix( const ActionOptions& ao ):

src/adjmat/ContactMatrixShortcut.cpp

@@ -77,6 +77,7 @@ void ContactMatrixShortcut::registerKeywords(Keywords& keys) {
   keys.add("compulsory","D_0","0.0","The d_0 parameter of the switching function");
   keys.add("compulsory","R_0","The r_0 parameter of the switching function");
   keys.add("numbered","SWITCH","specify the switching function to use between two sets of indistinguishable atoms");
+  keys.linkActionInDocs("SWITCH","LESS_THAN");
   keys.addActionNameSuffix("_PROPER"); keys.needsAction("TRANSPOSE"); keys.needsAction("CONCATENATE");
 }
 

src/adjmat/DistanceMatrix.cpp

@@ -21,7 +21,6 @@
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */
 #include "AdjacencyMatrixBase.h"
 #include "core/ActionRegister.h"
-#include "tools/SwitchingFunction.h"
 #include "tools/Matrix.h"
 
 //+PLUMEDOC MATRIX DISTANCE_MATRIX

src/adjmat/HbondMatrix.cpp

@@ -101,10 +101,13 @@ void HbondMatrix::registerKeywords( Keywords& keys ) {
   keys.add("atoms","HYDROGENS","The list of atoms that can form the bridge between the two interesting parts "
            "of the structure.");
   keys.add("numbered","SWITCH","The switchingfunction that specifies how close a pair of atoms must be together for there to be a hydrogen bond between them");
+  keys.linkActionInDocs("SWITCH","LESS_THAN");
   keys.add("numbered","HSWITCH","The switchingfunction that specifies how close the hydrogen must be to the donor atom of the hydrogen bond for it to be "
            "considered a hydrogen bond");
+  keys.linkActionInDocs("HSWITCH","LESS_THAN");
   keys.add("numbered","ASWITCH","A switchingfunction that is used to specify what the angle between the vector connecting the donor atom to the acceptor atom and "
            "the vector connecting the donor atom to the hydrogen must be in order for it considered to be a hydrogen bond");
+  keys.linkActionInDocs("ASWITCH","LESS_THAN");
 }
 
 HbondMatrix::HbondMatrix(const ActionOptions&ao):

src/adjmat/TopologyMatrix.cpp

@@ -72,10 +72,14 @@ void TopologyMatrix::registerKeywords( Keywords& keys ) {
   keys.add("compulsory","SWITCH","This keyword is used if you want to employ an alternative to the continuous swiching function defined above. "
            "The following provides information on the \\ref switchingfunction that are available. "
            "When this keyword is present you no longer need the NN, MM, D_0 and R_0 keywords.");
+  keys.linkActionInDocs("SWITCH","LESS_THAN");
   keys.add("compulsory","RADIUS","");
+  keys.linkActionInDocs("RADIUS","LESS_THAN");
   keys.add("compulsory","CYLINDER_SWITCH","a switching function on ( r_ij . r_ik - 1 )/r_ij");
+  keys.linkActionInDocs("CYLINDER_SWITCH","LESS_THAN");
   keys.add("compulsory","BIN_SIZE","the size to use for the bins");
   keys.add("compulsory","DENSITY_THRESHOLD","");
+  keys.linkActionInDocs("DENSITY_THRESHOLD","LESS_THAN");
   keys.add("compulsory","SIGMA","the width of the function to be used for kernel density estimation");
   keys.add("compulsory","KERNEL","gaussian","the type of kernel function to be used");
 }

src/cltools/GenJson.cpp

@@ -52,6 +52,7 @@ class GenJson : public CLTool {
 private:
   std::string version;
   void printHyperlink(std::string action );
+  void printKeywordDocs( const std::string& k, const std::string& mydescrip, const Keywords& keys );
 public:
   static void registerKeywords( Keywords& keys );
   explicit GenJson(const CLToolOptions& co );
@@ -90,6 +91,10 @@ void GenJson::printHyperlink( std::string action ) {
   std::cout<<".html\","<<std::endl;
 }
 
+void GenJson::printKeywordDocs( const std::string& k, const std::string& mydescrip, const Keywords& keys ) {
+  std::cout<<"       \""<<k<<"\" : { \"type\": \""<<keys.getStyle(k)<<"\", \"description\": \""<<mydescrip<<"\", \"multiple\": "<<keys.numbered(k)<<", \"actionlink\": \""<<keys.getLinkedActions(k)<<"\"";
+}
+
 int GenJson::main(FILE* in, FILE*out,Communicator& pc) {
   std::string line(""), actionfile; parse("--actions",actionfile);
   IFile myfile; myfile.open(actionfile); bool stat;
@@ -133,9 +138,13 @@ int GenJson::main(FILE* in, FILE*out,Communicator& pc) {
       std::size_t dot=desc.find_first_of("."); std::string mydescrip = desc.substr(0,dot);
       if( mydescrip.find("\\")!=std::string::npos ) error("found invalid backslash character documentation for keyword " + keys.getKeyword(j) + " in action " + action_names[i] );
       std::string argtype = keys.getArgumentType( keys.getKeyword(j) );
-      if( argtype.length()>0 ) std::cout<<"       \""<<keys.getKeyword(j)<<"\" : { \"type\": \""<<keys.getStyle(keys.getKeyword(j))<<"\", \"description\": \""<<mydescrip<<"\", \"multiple\": "<<keys.numbered( keys.getKeyword(j) )<<", \"argtype\": \""<<argtype<<"\"}";
-      else if( defa.length()>0 ) std::cout<<"       \""<<keys.getKeyword(j)<<"\" : { \"type\": \""<<keys.getStyle(keys.getKeyword(j))<<"\", \"description\": \""<<mydescrip<<"\", \"multiple\": "<<keys.numbered( keys.getKeyword(j) )<<", \"default\": \""<<defa<<"\"}";
-      else std::cout<<"       \""<<keys.getKeyword(j)<<"\" : { \"type\": \""<<keys.getStyle(keys.getKeyword(j))<<"\", \"description\": \""<<mydescrip<<"\", \"multiple\": "<<keys.numbered( keys.getKeyword(j) )<<"}";
+      if( argtype.length()>0 ) {
+          printKeywordDocs( keys.getKeyword(j), mydescrip, keys ); std::cout<<", \"argtype\": \""<<argtype<<"\"}";
+      } else if( defa.length()>0 ) {
+          printKeywordDocs( keys.getKeyword(j), mydescrip, keys ); std::cout<<", \"default\": \""<<defa<<"\"}";
+      } else {
+          printKeywordDocs( keys.getKeyword(j), mydescrip, keys ); std::cout<<"}"; 
+      }
       if( j==keys.size()-1 && !keys.exists("HAS_VALUES") ) std::cout<<std::endl; else std::cout<<","<<std::endl;
     }
     if( keys.exists("HAS_VALUES") ) {

src/colvar/ContactMap.cpp

@@ -134,7 +134,7 @@ void ContactMap::registerKeywords( Keywords& keys ) {
   keys.add("numbered","WEIGHT","A weight value for a given contact, by default is 1.0 "
            "You can either specify a global weight value using WEIGHT or one "
            "weight value for each contact.");
-  keys.reset_style("SWITCH","compulsory");
+  keys.reset_style("SWITCH","compulsory"); keys.linkActionInDocs("SWITCH","LESS_THAN");
   keys.addFlag("SUM",false,"calculate the sum of all the contacts in the input");
   keys.addFlag("CMDIST",false,"calculate the distance with respect to the provided reference contact map");
   keys.addFlag("SERIAL",false,"Perform the calculation in serial - for debug purpose");

src/colvar/Coordination.cpp

@@ -113,6 +113,7 @@ void Coordination::registerKeywords( Keywords& keys ) {
   keys.add("optional","SWITCH","This keyword is used if you want to employ an alternative to the continuous switching function defined above. "
            "The following provides information on the \\ref switchingfunction that are available. "
            "When this keyword is present you no longer need the NN, MM, D_0 and R_0 keywords.");
+  keys.linkActionInDocs("SWITCH","LESS_THAN");
   keys.setValueDescription("scalar","the value of the coordination");
 }
 

src/function/Bessel.cpp

@@ -24,7 +24,6 @@
 #include "FunctionOfScalar.h"
 #include "FunctionOfVector.h"
 #include "core/ActionRegister.h"
-#include "tools/SwitchingFunction.h"
 #include <array>
 #include <cmath>
 

src/function/Between.cpp

@@ -34,6 +34,57 @@ 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:
+
+\f[
+P(s) = \sum_i K\left( \frac{s - s_i}{w} \right)
+\f]
+
+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:
+
+\f[
+w(s) = \int_a^b \sum_i K\left( \frac{s - s_i}{w} \right)
+\f]
+
+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:
+
+KEYWORD={TYPE UPPER=\f$a\f$ LOWER=\f$b\f$ SMEAR=\f$\frac{w}{b-a}\f$}
+
+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:
+
+<table align=center frame=void width=95%% cellpadding=5%%>
+<tr>
+<td> TYPE </td> <td> FUNCTION </td>
+</tr> <tr>
+<td> GAUSSIAN </td> <td> \f$\frac{1}{\sqrt{2\pi}w} \exp\left( -\frac{(s-s_i)^2}{2w^2} \right)\f$ </td>
+</tr> <tr>
+<td> TRIANGULAR </td> <td> \f$ \frac{1}{2w} \left( 1. - \left| \frac{s-s_i}{w} \right| \right) \quad \frac{s-s_i}{w}<1 \f$ </td>
+</tr>
+</table>
+
+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
+
+KEYWORD={TYPE UPPER=\f$a\f$ LOWER=\f$b\f$ NBINS=\f$n\f$ SMEAR=\f$\frac{w}{n(b-a)}\f$}
+
+This specification would calculate the following vector of quantities:
+
+\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]
+
+
 \par Examples
 
 */

src/function/LessThan.cpp

@@ -34,6 +34,143 @@ namespace function {
 /*
 Use a switching function to determine how many of the input variables are less than a certain cutoff.
 
+Switching functions \f$s(r)\f$ take a minimum of one input parameter \f$r_0\f$.
+For \f$r \le d_0 \quad s(r)=1.0\f$ while for \f$r > 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 <list of parameters>}
+\endverbatim
+
+The following table contains a list of the various switching functions that are available in PLUMED 2
+together with an example input.
+
+<table align=center frame=void width=95%% cellpadding=5%%>
+<tr>
+<td> TYPE </td> <td> FUNCTION </td> <td> EXAMPLE INPUT </td> <td> DEFAULT PARAMETERS </td>
+</tr> <tr> <td>RATIONAL </td> <td>
+\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$
+</td> <td>
+{RATIONAL R_0=\f$r_0\f$ D_0=\f$d_0\f$ NN=\f$n\f$ MM=\f$m\f$}
+</td> <td> \f$d_0=0.0\f$, \f$n=6\f$, \f$m=2n\f$ </td>
+</tr> <tr>
+<td> EXP </td> <td>
+\f$
+s(r)=\exp\left(-\frac{ r - d_0 }{ r_0 }\right)
+\f$
+</td> <td>
+{EXP  R_0=\f$r_0\f$ D_0=\f$d_0\f$}
+</td> <td> \f$d_0=0.0\f$ </td>
+</tr> <tr>
+<td> GAUSSIAN </td> <td>
+\f$
+s(r)=\exp\left(-\frac{ (r - d_0)^2 }{ 2r_0^2 }\right)
+\f$
+</td> <td>
+{GAUSSIAN R_0=\f$r_0\f$ D_0=\f$d_0\f$}
+</td> <td> \f$d_0=0.0\f$ </td>
+</tr> <tr>
+<td> SMAP </td> <td>
+\f$
+s(r) = \left[ 1 + ( 2^{a/b} -1 )\left( \frac{r-d_0}{r_0} \right)^a \right]^{-b/a}
+\f$
+</td> <td>
+{SMAP R_0=\f$r_0\f$ D_0=\f$d_0\f$ A=\f$a\f$ B=\f$b\f$}
+</td> <td> \f$d_0=0.0\f$ </td>
+</tr> <tr>
+<td> Q </td> <td>
+\f$
+s(r) = \frac{1}{1 + \exp(\beta(r_{ij} - \lambda r_{ij}^0))}
+\f$
+</td> <td>
+{Q REF=\f$r_{ij}^0\f$ BETA=\f$\beta\f$ LAMBDA=\f$\lambda\f$ }
+</td> <td> \f$\lambda=1.8\f$,  \f$\beta=50 nm^-1\f$ (all-atom)<br/>\f$\lambda=1.5\f$,  \f$\beta=50 nm^-1\f$ (coarse-grained)  </td>
+</tr> <tr>
+<td> CUBIC </td> <td>
+\f$
+s(r) = (y-1)^2(1+2y) \qquad \textrm{where} \quad y = \frac{r - r_1}{r_0-r_1}
+\f$
+</td> <td>
+{CUBIC D_0=\f$r_1\f$ D_MAX=\f$r_0\f$}
+</td> <td> </td>
+</tr> <tr>
+<td> TANH </td> <td>
+\f$
+s(r) = 1 - \tanh\left( \frac{ r - d_0 }{ r_0 } \right)
+\f$
+</td> <td>
+{TANH R_0=\f$r_0\f$ D_0=\f$d_0\f$}
+</td> <td> </td>
+</tr> <tr>
+<td> COSINUS </td> <td>
+\f$s(r) =\left\{\begin{array}{ll}
+   1                                                           & \mathrm{if } r \leq d_0 \\
+   0.5 \left( \cos ( \frac{ r - d_0 }{ r_0 } \pi ) + 1 \right) & \mathrm{if } d_0 < r\leq d_0 + r_0 \\
+   0                                                           & \mathrm{if } r > d_0 + r_0
+  \end{array}\right.
+\f$
+</td> <td>
+{COSINUS R_0=\f$r_0\f$ D_0=\f$d_0\f$}
+</td> <td> </td>
+</tr> <tr>
+<td> CUSTOM </td> <td>
+\f$
+s(r) = FUNC
+\f$
+</td> <td>
+{CUSTOM FUNC=1/(1+x^6) R_0=\f$r_0\f$ D_0=\f$d_0\f$}
+</td> <td> </td>
+</tr>
+</table>
+
+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.
+
 \par Examples
 
 */

src/multicolvar/MultiColvarShortcuts.cpp

@@ -31,10 +31,12 @@ void MultiColvarShortcuts::shortcutKeywords( Keywords& keys ) {
   keys.add("numbered","LESS_THAN","calculate the number of variables that are less than a certain target value. "
            "This quantity is calculated using \\f$\\sum_i \\sigma(s_i)\\f$, where \\f$\\sigma(s)\\f$ "
            "is a \\ref switchingfunction.");
+  keys.linkActionInDocs("LESS_THAN","LESS_THAN");
   keys.addOutputComponent("lessthan","LESS_THAN","scalar","the number of colvars that have a value less than a threshold");
   keys.add("numbered","MORE_THAN","calculate the number of variables that are more than a certain target value. "
            "This quantity is calculated using \\f$\\sum_i 1 - \\sigma(s_i)\\f$, where \\f$\\sigma(s)\\f$ "
            "is a \\ref switchingfunction.");
+  keys.linkActionInDocs("MORE_THAN","MORE_THAN");
   keys.addOutputComponent("morethan","MORE_THAN","scalar","the number of colvars that have a value more than a threshold");
   keys.add("optional","ALT_MIN","calculate the minimum value. "
            "To make this quantity continuous the minimum is calculated using "
@@ -54,6 +56,7 @@ void MultiColvarShortcuts::shortcutKeywords( Keywords& keys ) {
   keys.add("numbered","BETWEEN","calculate the number of values that are within a certain range. "
            "These quantities are calculated using kernel density estimation as described on "
            "\\ref histogrambead.");
+  keys.linkActionInDocs("BETWEEN","BETWEEN");
   keys.addOutputComponent("between","BETWEEN","scalar","the number of colvars that have a value that lies in a particular interval");
   keys.addFlag("HIGHEST",false,"this flag allows you to recover the highest of these variables.");
   keys.addOutputComponent("highest","HIGHEST","scalar","the largest of the colvars");

src/secondarystructure/SecondaryStructureRMSD.cpp

@@ -83,6 +83,7 @@ void SecondaryStructureRMSD::registerKeywords( Keywords& keys ) {
   keys.addFlag("VERBOSE",false,"write a more detailed output");
   keys.add("optional","LESS_THAN","calculate the number of a residue segments that are within a certain target distance of this secondary structure type. "
            "This quantity is calculated using \\f$\\sum_i \\sigma(s_i)\\f$, where \\f$\\sigma(s)\\f$ is a \\ref switchingfunction.");
+  keys.linkActionInDocs("LESS_THAN","LESS_THAN");
   keys.add("optional","R_0","The r_0 parameter of the switching function.");
   keys.add("compulsory","D_0","0.0","The d_0 parameter of the switching function");
   keys.add("compulsory","NN","8","The n parameter of the switching function");

src/symfunc/CoordinationNumbers.cpp

@@ -110,6 +110,7 @@ void CoordinationNumbers::shortcutKeywords( Keywords& keys ) {
   keys.add("compulsory","D_0","0.0","The d_0 parameter of the switching function");
   keys.add("compulsory","R_0","The r_0 parameter of the switching function");
   keys.add("optional","SWITCH","the switching function that it used in the construction of the contact matrix");
+  keys.linkActionInDocs("SWITCH","LESS_THAN");
   multicolvar::MultiColvarShortcuts::shortcutKeywords( keys );
   keys.needsAction("CONTACT_MATRIX"); keys.needsAction("GROUP");
 }

src/symfunc/SMAC.cpp

@@ -55,8 +55,10 @@ void SMAC::registerKeywords(Keywords& keys) {
   keys.add("optional","SWITCH","This keyword is used if you want to employ an alternative to the continuous swiching function defined above. "
            "The following provides information on the \\ref switchingfunction that are available. "
            "When this keyword is present you no longer need the NN, MM, D_0 and R_0 keywords.");
+  keys.linkActionInDocs("SWITCH","LESS_THAN");
   keys.add("numbered","KERNEL","The kernels used in the function of the angle");
   keys.add("optional","SWITCH_COORD","This keyword is used to define the coordination switching function.");
+  keys.linkActionInDocs("SWITCH_COORD","LESS_THAN");
   keys.reset_style("KERNEL","optional");
   keys.setValueDescription("vector","the value of the smac parameter for each of the input molecules");
   multicolvar::MultiColvarShortcuts::shortcutKeywords( keys );